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Preface 



RDOS is an acronym for Data General's Real-time 
Disk Operating System; DOS stands for Disk Operating 
System. In an hour or two, you can develop a working 
sense of either system by using it. This book leads you 
through the steps required to: 

• Talk to the system through the Command Line 
Interpreter (CLI); 

• Write programs with a text editor program; 

• Produce and run a FORTRAN IV program; 

• Program in Extended BASIC; and 

• Write, produce debug, and execute an assembly 
language program. 

We don't attempt to describe all features of your 
operating system, the CLI, other utility programs, or 
the compilers you'll be using. These are all described 
completely in the manuals listed below. 

If your operating system is new to you, this book will 
give you a practical basis for using it. If you want to 
generate a system (which someone must do before you 
can really use this manual), see How to Load and 
Generate Your RDOS System for RDOS, or the 
appropriate chapter of The DOS Reference Manual Tor 
DOS. After you have generated a system, return to this 
manual. 

If you plan to program in an advanced language other 
than FORTRAN IV or BASIC, you'll be using a 
different compiler, but the material on the CLI and 

assembly language will be useful nonetheless. 



Reader, Please Note: 

We use these conventions for command formats in this 
manual: 



COMMAND required [optional] ... 

Where Means 

COMMAND You must enter the command (or 
its accepted abbreviation) as 
shown. 



required You must enter some argument 

(such as a filename). Sometimes, 
we use: 



(required, 
1 required 2 



which means you must enter one of 
the arguments. Don't enter the 
braces; they only set off the choice. 



[optional] You have the option of entering 

this argument. Don't enter the 
brackets; they only set off what's 
optional. 

You may repeat the preceding 
entry or entries. The explanation 
will tell you exactly what you may 
repeat. 
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Additionally, we use certain symbols in special ways: 
Symbol Means 

) Press the RETURN key on your 

terminal's keyboard. 

C Be sure to put a space here, (We use 

this only when we must; normally, 
you can see where to put spaces.) 

All numbers are decimal unless we indicate otherwise- 
e.g., 35,. 

Finally, in examples we use 

THIS TYPEFACE TO SHOW YOUR ENTRY) 

THIS TYPEFACE FOR SYSTEM QUERIES AND 

RESPONSES. 

Ris the RDOS/DOS CLI prompt. 



Related Manuals 

We list these manuals by name and number here; you 
can find them described in context as you read this" 
book. 



Extended Assembler User's Manual, 093-000040 or 

093-000139 

basic BASIC, 093-000088 

Extended BASIC User's Manual, 093-000065 

Extended BASIC System Manager s Guide, 093-000 1 1 9 

Command Line Interpreter User s Manual, 093-000 1 09 

Symbolic Debugger, 093-000044 

DOS Reference Manual, 093-00020 1 

FOR TRAN 1 1 ' User s Manual. 093-000053 

FOR TRAN I V Runtime Library, 093-000068 

FOR TRAN Commercial Subroutine, 093-000107 

How to Load and Generate Your R DOS System 

093-000188 

Extended Relocatable Loaders User s Manual 

093-000080 

Macroassembler User's Manual, 093-000081 

Introduction to Programming the NO VA ™ Computers 

093-000067 

Introduction to RDOS, 069-000002 (A technical primer) 

RDOS Reference Manual, 093-000075 (the primary 

technical book on RDOS) 

RDOS/DOS User's Handbook, 093-000105 (a handy 

summary of RDOS and DOS utility commands and 

errors) 

Supercdit Text Editor User 's Manual (RDOS/DOS), 

093-000111 

How to Generate Your DOS System, 093-000222 



End of Preface 
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Chapter 1 
Terms and Concepts 



What are RDOS and DOS? 

The Real-time Disk Operating Svstem (RDOS) is a 
general-purpose software package that can support 
r n C f^ ,me comroi - batch - or program development 
RDOS runs on NOVA ' and ECLIPSE'computers' it 
can use many different kinds of disks, and supports up 
to Di2K bytes of memory. 

The Disk Operating System (DOS) is a compatible 
subset of RDOS, and supports up to 64K bvtes of 
memory. DOS runs on diskettes or hard disks on 
NOV a and microNOV'A ™ computers. 

!i° l , h , R r? 0S "^ ° 0S PermU mu,ti ^king. This means 
that different program tasks can run concurrently, and 
that each task can respond individually to its own 
environment. Multitasking can make a program more 
efficient by permitting it to do useful processing while 
waiting for a slow peripheral device to complete an 
operation. However, multitasking is outside the scope 
of this book. You can find more information on 
multitasking in Chapter 5 of vour RDOS or DOS 
Reference Manual. 



How Do I Develop Programs? 

Depending on your programming language interests 
you 11 use one or more system programs or utilities 
(two terms we use interchangeably). You'll always 
need the CLI, whose operating procedures we describe 
m Chapters 2 and 3, and whose common commands we 
survey m Chapter 4. 

Unless you're a BASIC programmer, you'll be using a 
text editor utility to write your programs. Chapter 5 

explains Superedit - one of our editors. 

If you are a FORTRAN IV programmer, this is the 
cycle you will follow from creating through executing a 
program: B 



1 ) Create a FORTRAN source file using Superedit. 

2) Compile the source file; compilation produces a 
binary file. 

3) Load the binary file with the required FORTR AN 
libraries; the result is an executable program. 

4) Execute the program. 

Chapter 6 leads you through the steps to produce and 
run a sample FORTRAN program. 

If you are a BASIC programmer, you need no system 
utilities except the CLI. Chapter 7 gives a capsule 
sketch of BASIC programming. 



If you are an assembly language programmer, vour 
procedure is much the same as the FORTRAN 

programmer's: 

1 ) Create an assembly language source file using 
Superedit. 

2) Assemble the source file; the assembly produces a 
binary file. Chapter 8 describes the assemblers. 

3) Load the binary file. This produces an executable 
program. 

4) Execute the program. 



Chapter 9 leads you through the procedures to create 
and execute an assembly language program. 

The remainder of this chapter describes two 
fundamental system concepts: memory management 

and files. 
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Managing Main Memory 

RDOS memory can be divided into two program 
grounds, called foreground and background; each 
ground can run a program. Memory can be mapped by 
a hardware map. which allows each program to use up 
to 32K of memory, or it can be unmapped and allow 
each to use somewhat less memory. DOS memory can 
run only one program at a time. 



Both systems provide several methods to increase the 
effective size of a program's address space: program 
swapping and overlays. Swapping and overlays allow 
several program segments to occupy the same area of 
main memory at different times. Since each area 
receives different code at different times, you can use a 
given memory area more efficiently. 



The details on mapping, swapping and overlays, 
however, are outside the scope of this manual. 
Chapters 3 through 6 of the RDOS Reference Manual, 
and Chapters 3 through 5 of the DOS Reference Manual, 
explore them further. 



What is a File? 

A ./?/<.> is a collection of information treated as a unit. 
This data can be discrete scraps of data, like April's 
sales figures or December's mortgage balances; or it 
can be unified program code which does useful work, 
such as sorting other data or computing interest. The 
first type of file is a data file and the second a program 
or sore file. Certain save files can read data files, act on 
what they read, and produce new, updated data files. 
Each utility program and compiler you received from 
Data General - including the Command Line 
Interpreter Program (CLI) and the operating system 
itself- is a save file. 

Files are stored on devices such as magnetic tapes and 
disks. Disk files are the most versatile, and your system 
, has a way of structuring and managing them. A disk file 
' can be very large or very small; the largest file can store 

millions of bytes; the smallest, bytes. 

You give n filename \o each disk file to identify it. 
Filenames have from 1 to 10 of the followingASCII 

characters: upper- and lowercase letters, numbers, or 
dollar sign ($). In filenames, upper- and lowercase 
letters are considered identical; for example, the 
system sees no difference between filenames TEST 
and Test. A disk filename can also have an 
"extension", which is a period followed by one or two 
legal filename characters; for example, TEST.FR. 



You can use any legal filenames and extensions for 
your files. But be aware that the system and its utility 
programs follow these conventions for filename 
extensions: 

• it requires CLI macro files to have the extension 
.MC. 

• It assumes (but does not require) that assembly 
language source files have the extension ,SR. 

• It assumes (but does not require) that FORTRAN 
source files have the extension .FR. 

• h assigns the extension .RBio the binary version of 
each source filename after compiling or assembling 
it. 

• It assigns executable program files the extension .Si-' 
(save) and overlay files the extension .OL after 
processing them. 

• It assigns the extension .DR to user directory names 
when you create the directories. 

• It assumes (but does not require) that library files 
have the extension .LB. 

• It uses the extension .CM for some temporary CLI 
files. 

We touch on all of these file types in this book. 

After you've created a few files, you'll need some way 
to keep track of their names. You may even want to 
group your files into logical sets. RDOS and DOS 
provide a mechanism called a directory io help you keep 
track of your files and to categorize them. A directory 
file contains and catalogs information used to access 
other files and devices. It's similar to the table of 
contents in a book. 

Each system allows you to create your own directories. 
You'll learn about creating and managing directories in 
the next chapters. 

Any file can be permanent or nonpermanem. Permanent 
files cannot be accidentally deleted but require special 
treatment in some CLI commands. All system files and 
files you create in this book will be nonpermanent. 
Later on, for more on this, consult the CHATR 
command in the CLI manual 



Let's Get Started 

If yours in an RDOS system, proceed to the next 
chapter; if you're running DOS, skip to Chapter 3. 



End of Chapter 
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Chapter 2 
At the Console- RDOS 



This chapter describes a sample session with RDOS and 
ihe CLI, and leads you through many of the things you 
do on the keyboard to create and organize files. When 
you've finished the session, you'll have a practical 
working knowledge of RDOS basics. CFor a session 
with DOS, see Chapter 3.) 

If you inadvertently depart from a step we describe, 
your later experiences may differ from the text 
description. This is ok; mistakes are a primary vehicle 
for learning, and the CLI will usually prevent disasters. 
If you get really lost, go back to the beginning of the 
section you are in and give the files and directories 
different names; for example, FILE A I. MC instead of 
FILEA.MC. 

Later on, you can find more detail on the features and 
ramifications of your commands in the RDOS/DOS 
Command Line Interpreter User's Manual or the RDOS 
Reference Manual. If you generated your own RDOS 

system, you already have some experience with RDOS. 

Starting Up (Bootstrapping) 

Turn your system console ON, and make sure it is ON 
LINE. On some DASHER™ displays, the LINE switch 
is in back of the console. If this console has both upper- 
and lowercase letters, set it in uppercase mode with the 
ALPHA LOCK key because the program that brings up 
the system doesn't accept lowercase letters. Later you 
can change back to upper- and lowercase mode. 

Press or turn the computer's POWER switch to ON and 
flip the disk power switch (not the LOAD/READY or 
START switch) to ON. If your system is on a 
removable disk and the diskette is not in its drive, 
insert it in drive and flip the LOAD/READY switch 
to READY (or press START). On any disk, wait for 
the READY light. 

Now, turn to the system console. If it shows an 
exclamation point (!) prompt, then you have a virtual 
or programmed 'console. If it shows nothing, then your 

computer has hardware data switches. 

For a machine with a programmed console, find nn in 
Table 2-1. Type 1000nnL (for example, 100033L) on 
the system console next to the ! prompt. Skip the next 
paragraph. 



Table 2-1. Disk Device Codes 



Disk Type Model No. 


Device 
Code (octal) 

nn - 


Set These 
Switches Up 
(Others 
Down):* 


Fixed-head 


Mode! 6001-08 
Model 6063/64 


20 

26 


0, 11 

0, 11, 13. 14 


Moving-head 


Model 6060/61 
All others 


27 
33 


0. 11, 13, 
14, 15 

0, 11, 12. 
14, 15 


* For a disk on the second controller, also set switch 10 up 



For a machine with hardware data switches, turn to the 
computer front panel and make sure the data switches 
are set properly for your type of disk, as shown in Table 
2-1. The data switches are toggle-type switches, 
numbered through 15. If the switches aren't set 
properly, fix them. (If your computer lacks automatic 
program load, see Chapter 2 of How to Load and 
Generate Your RDOS System for the manual load 
procedure.) Now, lift the RESET switch, then the 
PROGRAM LOAD switch. 

For either type of computer, the system console will 
ask; 

FILENAME? 



It's asking for the name of your RDOS system. If the 
person who generated this system gave it any name 
other than SY'S, you must type that name; but let's 
assume it was named SYS. To indicate SYS, type SYS 
and press the RETURN key ()), or simply press ). 
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FILENAME? ) 

RDOS REVx.xx (x.xx is the revision number) 

DATE (M/D/Y)? 

(If you receive the message FILE NOT FOUND: 

SYS.SV, try to discover (or remember) the system's 
name; then type this name and ).) 

Answer the date/time questions: 

FILENAME? } 
RDOS REVx.xx 

DATE (M/D/V)?4 2 79) 

TIME (H:M:S)? 13 10) (Hours in 24) 

R 



R is the CLI prompt; it means that the CLI is ready to 
accept a command. You'll see it hundreds of times in 

the future. You can now switch to upper- and 
lowercase, if this applies. RDOS will translate lowercase 
letters to uppercase. 

Typing Mistakes, Control Characters 
and BREAK Key 

If you type a faulty command and press ) without 
realizing that you've typed in a faulty command, the 
CLI will respond with an error message - usually FILE 
DOES NOT EXIST: fauiiy-cmry- and will return'the R 
prompt. If you want to correct a line before pressing 
return, simply press the DEL or RUBOUT key 
sequentially to erase characters from rieht to left (On 
printer consoles DEL or RUBOUT echoes a backarrow 
(-) or underscore (_) for each character erased.) You 
can erase an entire line by tvpine backslash (\) or 
SHIFT-L. 

To stop execution of any CLI command or utility 
program (except an editor), press the CTRL key hold 
it down, then press A. CTRL-A halts the command or 
program and returns the R prompt. 

You can interrupt output to your console at anv time by 
typing CTRL-S. The output won't be lost; vou can 
continue it from the point of CTRL-S by typing 
CTRL-Q. You can use CTRL-S and CTRL-Q * 

intermittently to read a long file on a display console. 

If your computer has a programmed console (! prompt), 
the BREAK key on the system console keyboard 
stops execution of all software. To continue with the 
program that was running, ivpc P) (uppercase P, 
then )). We mention this here because, in the course 
of bringing up and running RDOS, vou may 
inadvertently hit the BREAK key. If everything stops 
and the system console shows .'. try typing P). " 



The Session 

If your system console has a display screen instead of a 
printer, you should record console dialog in the disk log 
file so that you can print and review it later. If the 
system console has a printer, it provides reviewable 
copy as you type; you don't need a disk log file and can 
proceed to the section called Master Directory Name 



Log File 

With a display terminal, type 

L1STLOG.CM) 

If there is an old LOG.CM log file on the disk, the 

screen will display 

LOG.CM 

and a number and letter, then the R prompt. Preserve 
the old log file by typing 

RENAME LOG.CM LOGOLD CM) 
R 

Next, whether or not there was an old log file, type 
LOG/H) 

to create a new log file, open it. and start recording 
console dialog in it. Later, to close the loe file you'll 
type ENDLOG ). 



Master Directory Name 

Next you should discover your master directory name 
so type: 

MDIR) 

The CLI returns the master directory name, which 
vanes with the type of disk you have. Generally it is 
cither DPO. DZO, or DSO. We use Dxxio indicate the 
master directory name, so you should mentally 
substitute the name returned from MDIR) for Dxxm 
this session. 

Creating Some Files 

The next step, naturally, is to create a file. The CLI 
offers several file-creating commands, and we choose 
CR AND: 



GRAND F1LEA) 
R 
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Voila. You now have an empty disk file named FiLEA. 
FILEA was an argument 10 your command; it told the 
CLI what to name the new file. Some CLI commands 
require arguments, others don't. 

You can verify FILEA's existence with the LIST 
command: 

LIST FILEA) 
FILEA. D 
R 

and remove FILEA with the DELETE command: 

DELETE/V FILEA) 
DELETED FILEA 
R 

The /V is a switch, which modifies the basic meaning of 
a command; here, it told the CLI to verify the deletion. 
Now, create a different version of FILEA: 

GRAND FILEA.MC) 

R 

Now there's an empty FILEA. MC on the disk. 

Normally, you'd use a text editor to put something in 
it, but you haven't reached Chapter 5 -- Creating and 
Editing Text— yet. You can, however, insert text by 
transferring it directiv from the console into 
FILEA. MC: 

XFER/A/B STT1FILEA.MC 

MESSAGE HELLO) 

CTRL-Z (Hold down CTRL key and press Z) 

R 

The CTRL and Z keys won't echo as characters on the 
console. On a display terminal, the R prompt may leap 
to the top of the screen when you type CTRL-Z. 'if so, 
type CTRL-L to clear the screen and proceed with a 
clear screen. 

You've just transferred the CLI command MESSAGE 
and the text string HELLO into FILEA. MC. The 
XFER command transfers the contents of one file (the 
console input file, STTI) to another file (disk file 
FILEA. MC). XFER requires two arguments; in this 
case, they were STTI and FILEA. MC. The /A switch 
specifies ASCII transfer; /B tells XFER to append to 
the existing file. If you omitted /B, XFER would try to 
create FILEA. MC, which would produce an error 
message because FILEA. MC already exists. 

Try to execute FILEA. MC: 

FiLEA) 
HELLO 

R 



Your FILEA. MC is a CLI macro. The .MC extension 
tells the CLI to execute all commands within it. You 
can omit the .MC extension to execute a file, but you 
must include it for all other commands that involve the 
file. Check FILEA. MC's statistics with LIST: 

L1ST/E FILEA. MC) 

FILEA. MC 14 D 04/02/79 13:20 04/02/79 [000444 JO 

R 

the /E switch tells the CLI to list every statistic about 
the file. These include byte-length (14). organization 
type (D means random), date and time created or last 
modified, date fast opened, starting disk block address 
in octal, and use count. Obviously, the central four 
categories will differ for your own FILEA. MC. 

To check the file's contents, type: 

TYPEFILEA.MC) 
MESSAGE HELLO 
R 

Now, you can add a little sophistication to FILEA. MC: 

XFER/A/B STTI FILEA. MC) 

MESSAGE HOW MANY BLOCKS ARE LEFT) 

MESSAGE ON THIS DISK? ;DISK) 

MESSAGE WHAT'S THE CURRENT DIRECTORY) 

GDIR) 

CTRL-Z 

R 

One problem with inserting text this way is that you 
can't edit. If you make a mistake and don't correct it 
before you terminate the line with a ),you must delete 
the file and rebuild it from the beginning. Having made 
no mistakes, check the improved macro: 

FILEA) 

HELLO 

HO W MA N Y BL OCKS ARE L EFT 

ON THIS DISK? 

LEFT: 9008 US ED: 768 

WHA T'S THE CURRENT DIRECTOR Y? 

Dxx 

R 



FILEA. MC is much larger now, as you can see: 

L1STFILEA.MC) 
FILEA.MC 1I8D 
R 

FILEA.MC now contains four MESSAGE commands, 
a DISK command, and a GDIR command. Each would 
work separately, but you've combined them. (Your 
own DISK figures may differ from those here). 
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Proceed to create another macro: 

XFER/ASTTI FILEB) 
TYPE F1LEA.MC) 
CTRL-Z 
R 

Here, FILEB doesn't exist, so XFER will create it, and 
you can omit the /B switch. By doing so, you saved two 
steps, the GRAND FILEB and the /B switch, but 
you've been a little careless: 

FILEB) 

FILE DOES NOT EXIST: FILEB. SV 

R 

The CLI looked for FILEB.MC, then for the save file, 
FILEB. SV; finding neither, it returned the error 
message. To fix it, give FILEB the .MC extension: 

RENAME FILEB FILEB.MC) 

R 

FILEB) 

MESSAGE HELLO 

MESSAGE HOW MANY BLOCKS ARE LEFT 
MESS A GE ON THIS DISK; DISK 



You planned to have your second file type your first 
file, and you succeeded. Now you'd like to compare the 
files, so you type LIST/E without an argument. See 
Figure 2-1. 



Your command told the CLI to list all nonpermanent 
files in the master directory; who knows how long the 
listing would have continued if you hadn't hit the 
CTRL-A keys to interrupt the command and return the 
CLI prompt. (Your own listing will differ from that 
above.) The letters following the byte count indicate 
file type and organization. 



There are some old friends in Figure 2-1: SYS.SV, 
CLI.SV (save files always end in .SV), and FILEA.MC 
If you generated your own RDOS svstem. vou'll 
recognize BOOT.SV. Unfortunately, FILEB.MC didn't 
show up. You could list the entire contents of directory 
Dxx to find FILEB.MC, but there's a better way: create 
a directory for the two macro files. 



Creating Some Directories 

There are two kinds of directories you can create: 
secondary partitions (whose size cannot change) and 
subdirectories (which are flexible). You decide on a 
subdirectory: 

CDIR MACRODIR) 
R 

Now, to move the macros into the new directory: 

MOVE/V MACRODIR FILEA.MC FILEB MC) 

FILEA.MC 

FILEB.MC 

R 



LIST/E) 
















SYS.SV 

DSKED.SV 

RLDR.SV 

CLI.OL 

BOOT.SV 

FILEA.MC 

CLI.SV 

CTRL-A 


3686A 
18«32 

«608 
«3008 

6656 

1 18 

10752 


SD 

SD 

SD 

C 

SD 

D 

SD 


03/26/79 
03/29/78 
13/23/78 

10/05/78 

10/05/78 
0«/02/79 
10/05/78 


13:36 

16:18 

13:16 
10: lu 
23:03 
13:2e 
liilti 


03/26/79 
03/29/78 
03/23/78 
03/30/79 

10/05/78 
0«/02/79 
10/05/76 


1002707] 
E001670] 
10157<M] 

C000366) 
[000522] 

[003«67] 






1 






1ST 

R 














_ __ 



Figure 2-1. Master Directory Listing 



2-4 



069-OOO022-O1 



The MOVE command copies the files into the new 
directory; the /V switch instructs the CLI to verify their 
names as they arrive. Now, the files are safely in 
MACRODIR; you can make M ACRODIR the current 
directory and then list the files in it: 



DIRMACRODiR) 

R 

LIST) 

FILEA.MC USD 

FILEB.MC 14 

R 

The DIR command makes MACRODIR the current 
directory. DIR also initializes a directory, if it hasn't 
been initialized. Initialization opens a directory for 
access to its files. The MOVE command - an exception 
to the rule - doesn't require initialization, but other 
commands do. Starting up RDOS automatically 
initializes the master directory, but you must 
specifically initialize other directories to use them. DIR 
does this for you. 



Now to delete the original files: 

DELETE/V FIELA.MC FILEB.MC) 
F1L EDOES NO T EX IS 77 FIELA . MC 
DELETED FILEB.MC 

R 

Typos are no-noes. 

DELETE/V FILEA) 

F1L EDOES NO T EX IS T: FIL EA 

R 

(sigh) 

DELETE/V FILEA.MC) 
DELETED FILEA.MC 
R 

At this point, your disk looks like Figure 2-2; the 
current directory is Dxx. 



' f- 1 * ■ ■ ., » . ■ fi tr -.'.: " 



Now you can check the current directory with another 
useful command: 



»777iF7IT»7T'Jl»i 



GD1R) 

MACRODIR 

R 



For neatness, let's delete the original files in master 
directory Dxx. First, get back to the master directory: 



D1R%MDIR%) 
R 



%MD!R% is a CLI variable that contains the master 
directory name. You can use it in command lines just as 
you'd use Dxx. 



'■'■v.':' ' - ' '••: '? A7-KjZ^%;^vpr^ 
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Figure 2-2. Disk with Subdirectory 
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Whenever you create a directory, ihe CLI assigns the 
extension .DR to its name. The CLI also assigns 
different extensions to files after they have been 
assembled, compiled, or loaded. .SV is another 
CLI-assigned extension. These extensions come in 
very handy when you want to access specific kinds of 
files. For example: 



L1STD-.DR) 
MACRODIR.DR 512 
R 



DY 



As explained in the Preface, the box represents a space; 
we use it only where a space isn't obvious in the format. 
The dash (-) is a template character, which in this case 
instructs the CLI to list ^//filenames that have the .DR 
extension. (Directories are also files.) Try it with save 
files: 

LfSTH-.SV) 

SYS.SV 39424 SD 
DSKED.SV 12288 SD 
RLDR.SV 4096 SD 
CLI.SV W240 SD 



Templates work only with certain commands, in certain 
contexts. Don't be afraid to experiment with them 
(except with DELETE); at worst, you'll get an error 

message. 

At this point, you can explore disk directories further. 
Your disk has the master directory (Dxx) and one 
subdirectory (MACRODIR). Because you've just 
started using your system, you don't have enough 
different kinds of files to require another directory. 
Eventually you will want others, and you may want 
some of them to be secondary partitions. So, make sure 
Dxx is the current directory, and create a secondary 
partition: 



DIR%MDIR%) 

R 

CPART ALPHA 

R 

LISTG-.DR) 

ALPHA.DR 

MACRODIR.DR 

R 



128) 



65536 
512 



CTY 
DY 



CTRL-A 

/AT 

R 

You could also have used the dash to list your .MC files 
on Dxx. Instead, you moved them and they're 
probably better off in their own directory. You could 
also list all files without an extension by typing LIST -.), 
or files whose names began with a letter or number: 

LISTCS-.-) 

SYS.Sy 39424 SD 

SEDIT.SV 9216 SD 

SYS.OL 27648 C 

CTRL-A 
1ST 

R 

Another template character is the asterisk, which 
means one character, as opposed to the dash, which 
means from zero to ten characters. To list all five-letter 
filenames which begin with Fand have two-character 
extensions, you'd type: 

LISTZF—V) 

FLOAD.SV 15072 SD 
FDVMP.SV 15360 SD 
R 

These files are the fast dump and fast load programs in 
the master directory. Note the absence of FILEA.MC 

and PILEB.MC, which are in MACRODIR. 



MACRODIR is a subdirectory and works by pointing to 

other files, hence it will never show more than 5 1 2 
bytes. ALPHA is a secondary partition, and will 
physically contain any files and subdirectories you place 
in it: naturally, these can never exceed the 128 disk 
blocks (65,536 bytes) you specified for ALPHA (128 
blocks at 512 bytes each equals 65,536 bytes). Proceed 
to build your file hierarchy: 

D1R ALPHA) 

R 

CDIR BETADIR) 

R 

LIST) 

BETAD1R.DR 512 DY 

R 

Give each new directory a little file: 

XFER/A STTi INALPHA.MC) 

MESSAGE I'M A FILE IN SECONDARY) 

MESSAGE PARTITION ALPHA ) 

CTRL-2 

R 

DIR BETADIR) 

R 

XFER/A STTI INBETAD1R.MC) 

MESSAGE I'M A FILE IN ALPHA'S) 

MESSAGE SUBDIRECTORY. BETADIR) 

CTRL-2 

R 

Now, your disk structure looks like Figure 2-3, the 
current direciorv is BETADIR. 
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Figure 2-3, Disk with Secondary Partition and Subdirectories 



The master directory, Dxx, is the primary partition; it 
has one secondary partition, ALPHA, and one 
subdirectory, M ACRODIR, ALPHA, in turn, has one 
subdirectory, BETADIR. 

Your directory structure is growing. Take a breather, 
and offer thanks for the GDIR and DIR commands. 'if 

the hierarchy seems too complex, you can always 
delete the new directories later. 

The system allows you to execute any file simply by 
typing the directory name, a colon, and the file name 
(of course, you could always DIR to the directory you 
wanted, then type the file name, but that requires an 
extra step). 

GDiR) 

BETADIR 

R 

1NALPHA) 

FIL EDOES NO T EXIST; IN A L PHA . S V 

R 

(True, in directory BETADIR.) Try a directory 

specifier: 

ALPHA:1NALPHA) 

/ \M A FILE IN SECONDA R Y 

PARTITION ALPHA. 

R 



Eureka. The directory specifier (:) also works with most 
other CLI commands: 

LIST ALPHA:1NALPHA.MC) 

ALPHA.iNALPHA.MC 57 

R 

TYPE ALPHA:INALPHA.MC) 

MESS A GE I 'M A FIL E IN SECONDA R Y 

MESS A GE PA R TITION ALPHA . 

R 



Try it with FILEA.MC in MACRODIR: 

MACROD!R:FILEA} 

HELLO 

HOW MANY BLOCKS ARE LEFT 

MESS A GE ON THIS DISK ? 

LEFT: 9 7 USED 31 

WHA T'S THE CURRENT DIRECTOR Y? 

BETADIR 

R 



This example shows two things: that DISK always 

returns the space left in the current partition (here, 
ALPHA), and that GDIR always returns the current 
directory name (even though a file in another directory 
issues GDIR). 
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There are some restrictions on directory specifiers; for 
example, they don't work with template characters: 

L1STMACR0DIR:-,MC} 
R 



Now that you've tried directory specifiers, you can use 
them to clarify the idea of initialization. The rules say 
that a directory must be initialized before you can 
access its files. Let's release M ACRODIR (remove its 
initialization), and see. 

RELEASE MACRODIR) 

R 

MACRODIR:F!LEA) 

SO SUCH DIRECTOR Y:\fA CRODIRtFILEA.SV 

R 



So we initialize MACRODIR again; 

INIT%MDIR%:MACRODIR) 

R 

MACRODIR:F!LEA) 

HELLO 



Link Entries 

At this point, you may be wondering how all this relates 
to useful processing. Well, we had to introduce the link 
entry somewhere; it can save you time and hundreds of 
blocks of disk space. When you begin to process data, 
you'll be linking from different directories to the big 
system utility assemblers or compilers in the master 
directory; this will allow you to assemble and compile 
files from any directory with almost no cost in extra 
disk space. 

A link entry is a filename whose sole function is to 
point to another filename in the same or in another 
directory. You can create a link entry with the LINK 
command and remove it with the UNLINK command; 
Don't use DELETE to remove a link because this will 
delete the file you linked to. 

GDIR) 

BETADIR 

R 

LINK FiLEA.MC MACRODiRiFiLEA.MCJ 

R 

LIST FILEA.MC) 

FIL EA . MC MA CR OD/R :FIL EA . MC 

R 



This is what a link entry looks like: no byte count or file 
organization key letter. 



We had to specify %MDIR% to initialize MACRODIR 
because MACRODIR is in the master directory, not in 
the current directory. When you initialize, you can 
choose between two commands: INIT and DIR. Use 
INIT when you don't want to change the current 
directory, and DIR when you do. 



There are situations where directory specifiers appear 
useful, but are not. They don't help when the file 
specified needs another file and can't find it; for 
example: 



MACRODiR:FlLEB) 

FILE DOES NOT ' EXISTtFlLEA. 

R 



MC 



Remember FILEB.MC? You wrote it to type 
FILEA.MC, and it did so; but now it cannot find 
FILEA.MC in the current directory, BETADIR. There 

are two ways to handle this: the obvious way, which 
requires deleting FILEB.MC and recreating it with a 
directory specifier (M ACRODIR:FILEA.MC), and the 

challenging, interesting way, which involves creating a 
link entry to F 1 L E A . M C . 



Now, when FILEB.MC searches current directory 
BETADIR for FILEA.MC, the link entry named 
FILEA.MC will point to MACRODIR: 

MACRODIR:FILEB) 

MESSAGE HELLO 

MESS A GEHO W MA N Y BL OCKS ARE LEFT 

MESS A GE ON THIS DISK ? 



Your link entry allowed FILEB to find FILEA. If 

you're dubious, remove the link: 

UNL1NK/V FILEA.MC) 

UNLINKED FILEA.MC 

R 

MACR0DIR:F1LEB) 

FILE DOES NOT EXlSTtFlLEA. MC 

R 

Convinced? Recreate the link: 

LINK FILEA.MC MACRODiR:FILEA.MC) 
R 
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You can use any name you want for a link, but if you 
forget it, your link will be useless. In this example, the 
link name had to be FILEA.MC because FILEB.MC 
would search for that name only. 



You'll use the same procedure to create all links. For 
example, the RDOS Macroassembler uses three files, 
which can require up to 250 disk blocks. You can link to 
the files from any directory, use the assembler, and 
consume only a few bytes per link. 



You have now created files, a subdirectory, a secondary 
partition, another subdirectory, and a link entry, and 
used the commands LOG, GRAND, LIST, DELETE, 
XFER, TYPE, MESSAGE, DISK, GDIR, RENAME, 
CTRL-A (not really a command, but an interrupt), 
GDIR, MOVE, DIR, CPART, INIT, RELEASE, 
LINK, and UNLINK. You've also used switches and 
template characters, - and *, and CLI variable 
%MDIR%. 

Your disk structure now looks like Figure 2-4. 
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Figure 2-4. Disk with Secondary Partition, Subdirectories and a Link Entry 
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Concluding the Session 

Before terminating your session, you should back up 
your disk material using the DUMP command. DUMP 
produces a special kind of copy file, which you can then 
LOAD back onto disk later should something either 
happen to the disk or if you delete the original files for 
more disk space. Both DUMP and LOAD offer useful 
switches, which can select files by date; they also accept 
template characters. 

DUMP can copy the current disk to mag tape, or a disk 
file. Unless you specify files, it copies the entire 
contents of the current directory, including all 
subordinate directories. To use mag tape, take a new 
reel and examine the inner part of the reel. On a new 
reel, you should see a plastic ring, called a write-enable 
ring. This ring allows the tape to be written upon. If 
there is no ring, insert one. Mount the tape on a drive, 
dial number for that drive, and make sure no other 
drive has the same number. Turn the unit ON, press 
LOAD, then ON LINE. Now, get into the disk 
directory you want to DUMP. (If you want to DUMP 
the entire disk, get into the master directory.) 

Initialize the tape: 

1NITMT0) 

You must always INIT a tape drive to use it. 

You can now DUMP your disk to the first file, file 0: 

DlRDxx) 
R 

DUMP/V MTO:0) 



The /V switch lists DUMPed file names on the console 
where, as console dialog, they will be recorded in the 
log file (if you opened one earlier). 



DUMP takes a little while to execute as it copies all files 
and file directory information to file of the tape; 
eventually you'll get the R prompt back. Type: 

RELEASE MTO) 
R 

This will rewind the tape and release the drive from the 
system. Take the drive off line, UNLOAD the tape, 
remove it from the drive, and store it; turn the drive 
OFF. Label the tape, noting the contents of the dump, 
the date, and the tape file number. The file number is 
very important; if you forget it and inadvertently 
DUMP to the same file later, you'll lose the original file 
and all subsequent files on the tape. For your next 
dump on this tape, DUMP to file 1, and then 2, and so 
on; if the tape is long enough, you can go to 99. Now, 
write the tape name or number and file number on the 
listing of DUMPed files, and put the listing in a 
notebook or other safe place. 

To DUMP to a disk or diskette, you can use the 
devicename and your own filename for the dumped 
material. If the disk or diskette is brand new, don't 
forget to run the disk initializer program on it, then 
type INIT/F to it before using it on your system. This 
procedure is described in How to Load and Generate 
Your RDOS System. Jo DUMP to DPI, for example, 
you'd place a disk or diskette in DPI and type: 

DIR°«=MD1R%) 

R 

INITDP1) 

R 

DUMP/V DP1:040279.DU) 



The /V switch lists dumped files on the console, where, 
as console dialog, they will be recorded in the log file (if 
you opened one earlier). The dump filename need not 
be 040279. DU; we used this name and extension 
because they indicate the date and file type. 
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Normally, whatever device you're dumping to, you'll 
want to dump selected flies, not the entire disk. To 
dump files by date, use the /A switch, which instructs 
the CLI to dump only those Tiles created or modified on 
or after a specific date. The counterpart of /A (after) is 
/B (before). 

(mT0:0 J 

DUMP/V < > 04-01 -79/A) 

(DP1 :040279. DU I 



You DUMP any specific directory from within it: 

D!R ALPHA) 
R 



DUMP/V 



MT0:n 
DPn:040279.DU 



By dumping a directory, you dump its contents" hence 
dumping ALPHA also dumps BETADIR. 



You can also use the template characters within the 
current directory. For example, to dump all save and 
overlay files from current directory Dxx, vou would 
type: 



DUMP/V destinationfile -.SV -.OL) 



Later on, to return the DUMPed files to the current 
directory, you must use the LOAD command. The /R 
switch, described under LOAD in Chapter 4, conflicts 
with identical filenames that exist in the current 

?* e .?. ory - After read - v ing the source device, vou must 
IMT it, then do the LOAD- 



DtR%MD!R%) 

( MTO 



INIT 

R 
LOAD/V 



DP1 



MT0:0 



You can also use locai date switches and the template 
characters in the LOAD command. 

At this point, we assume that you've DUMPed all the 
files you created during this session. If you want, you 
can now delete them and restore the disk to its original 
state with only the system files on master directory 
Dxx. This requires little effort: 

DIR%MDIR%) 

R 

RELEASE ALPHA) 
R 

DELETE/V ALPHA.DR) 
DELETED ALPHA. DR 
R 

RELEASE MACRODIR) 
R 

DELETE/V MACRODIR.DR) 

DELETED MACRODIR. DR 

R 

The RELEASE command removes the directory or 
device that you introduced by INIT (or DIR) to "the 
system. It also releases any subordinate directories. At 
this point, if you opened log file LOG.CM earlier, you 
might want to close it and print it. This will give you a 
hard-copy record of your dialog with the CLI. If you 
have a line printer, turn it on, place it ON LINE, and 
type: 

ENDLOG) 

R 

DfR%MDlR%) 

R 

PRINT LOG.CM) 



R 



If you have no line printer, but have a printing console 
connected to the second keyboard/printer interface, 
type: 

ENDLOG) 

R 

DIR%MDIR%) 

R 

XFER/A LOG.CM STT01 } 



DP1:040279.DU 
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To access LOG. CM. you must be in, or use a directory 

specifier to, the master directory because you started 
the log file in the master directory. For more on LOG 
and any other commands you've used, see the 
command in Chapter 4 or in the CLI User's Manual. 
The log file is quite large by now (check it with LIST 
LOG. CM); you might want to delete it. 



Now, you can release the master directory and shut 
down the system. You can release any directory from 
any directory -- including itseif. Type: 

RELEASE %MD1R%) 

Releasing the master directory updates the disk with al 
new file information and shuts down the operating 
system. The CLI and RDOS sign off with the message 



MASTER DEVICE RELEASED 

You can now flip the disk switch to LOAD, wait for the 
LOAD light (if this applies), then turn off the disk 
drive, computer, console, and line printer. 

Congratulations. You've just completed a session with 
RDOS. This isn't a toddler's lesson; it includes most of 
the concepts and commands you'll use in your 
day-to-day interaction with RDOS, and it provides a 
sound background for the intricacies of other CLI 
commands and RDOS itself. 

You can find details on certain CLI commands in 
Chapter 4; these are covered more deeply in the CLI 
User's Manual. You may feel ready to proceed to 
Chapter 5, which describes using the Superedit 
text-editing utility. 



End of Chapter 
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Chapter 3 
At the Console - DOS 



This chapter describes a sample session with DOS and 
theCLI, and leads you through many of the things you 
would do on the keyboard to create and organize Tiles. 
When you've finished the session, you'll have a 
practical working knowledge of DOS basics. (For a 
session with RDOS, see Chapter 2.) 

If you inadvertently depart from a step we describe, 
your later experiences may differ from the text 
description. This is ok; mistakes are a primary vehicle 
for learning and theCLI will usually prevent disasters. 
. If you get really lost, go back to the beginning of the 
section you are in and give the files and directories 
different names; for example, FILEA I.MC instead of 
FILEA.MC. 

Later on, you can find more detail on the features and 
ramifications of your commands in the RDOS/DOS CLl 
User's Manual or the DOS Reference Manual. If you 
generated your own DOS system, you already have 
some experience with DOS. 

This session assumes that you'll be using a hard disk 
with diskette or dual-diskette drive and that the system 
disk(ette) will be in drive 0. You can, however, do 
almost everything in this chapter with a single diskette 
drive. 

Within this chapter and book, the word disk means 
either hard disk or diskette; diskette means only 
diskette. 



Program Load Steps (Bootstrapping) 

Turn your system console ON, and make sure it is ON 
LINE. On some DASHER ™ displays, the LINE switch 
is in back of the console. If this console has both upper- 

and lowercase letters, set it in uppercase mode with the 
ALPHA LOCK key because the program that brings up 
the system doesn't accept lowercase letters. Later you 
can change back to upper- and lowercase mode. 

Turn or press the computer power switch to ON or 
RUN, whichever applies. Turn the disk or diskette 
drive ON. If your DOS system is on a removable 
hard-disk cartridge, make sure this cartridge is in its 
drive; press the LOAD/READY switch UNREADY. 
For any hard disk, wait for the READY lamp to liuht. 



For diskette-based DOS, make sure the write-protect 
hole of the system diskette is taped. Then insert this 
diskette in diskette drive and close the door. (If you 
don't know which drive is 0. try the left; then if 
program loading doesn't work, try the right. The one 
that works is drive 0.) 

Look at the system console. If it shows an exclamation 
point (!) prompt, then you have a virtual or 
programmed console. If it shows nothing, then your 
computer has either a hand-held console, console 
debug, or CPU program load. 



Computers with Programmed Consoles 

For a microNOVA machine with a programmed 
console, find n in Table 3-1. Type nL (for example, 
100026L) on the system console. Skip to Bnmiinv Up 
DOS. ' ' 

For a NOVA computer with a programmed console, 
type 100033Lon the system console. Skip to Brineine 
Up DOS. ' 



Table 3-1. microNOVA Device Codes 



Disk type: 



Hard, sealed disk (hard disk 
without a LOAD/READY 
switch). 



Hard dual-platter disk 
subsystem (disk drive with a 
LOAD/READY or 
LOAD/RUN switch). 



Double-density diskette (these 
drives have a lamp in the center 
of the latch). 



Single-density diskette (these 
drives have three lamps above 
the diskette slot). 



100026 



100027 



100026 



33 
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Computers without Programmed 
Consoles 

If you have a microNOV'A computer with a hand-held 
console (a small box that is initially attached to the 
computer panel but can be detached; looks like a small 
calculator), press the RESET and CLR-D keys on the 
hand-held console. Find the appropriate nin Table 3-1 
(for example, 100026) and enter nin the hand-held 
console with the number keys. Press the PR LOAD kev 
a n d s k i p t o Bringing Up DOS. 

If your microNOVA doesn't have a hand-held console, 
it has either console debug or CPU program load. Press 
the rocker switch on the computer front panel to the 
PL/START position. If the system console then 
displays a question, you have CPU program load; skip 
to Brmgmg Up DOS, below. If the rocker switch has no 
effect, then you have console debug. This works the 
same way as a programmed console, so go back and 
execute the steps described for programmed console 
machines. 

If you have a NOVA computer with hardware data 
switches, look at the computer front panel and make 
sure the data switches are set to 1 00033 octal (switches 
0, 1 1, 12, 14, and 15 up, the others down). If the 
switches aren't set properly, fix them. (The data 
switches are toggle-type switches, numbered through 
15.) Lift the RESET switch, then the PROGRAM 
LOAD switch and proceed. 

Bringing Up DOS 

After your program load steps, the system console will 
ask: 

FILENAME? 

It's asking for the name of your DOS system. (If 
nothing happens, place the diskette in the other drive, 

and execute the program load steps again.) If the 
person who generated this system gave it any name 
other than SYS, you must type that name; but let's 
assume it was named SYS. To indicate SYS simply 
press the RETURN key ()): 

FILES A ME 7 ) 

DOS REVx.xx (x.xxh the revision number) 

DATE (MIDI)')? 



If you receive the message FILE NOT FOUND: { 

SYS.SK make sure that the diskette in DP0 contains a 
system, and try to discover (or remember) its name; 
then type this name and answer the date/time 
questions: 



FILENAME? ) 

DOS REVx.xx 

DATE (MIDI)')? 4279) 

TIME (H:M:S) ? 1 3 1 ) (hoursin24) 

R 

R is the CLI prompt; it means that the CLI is ready to 
accept a command. You'll see it hundreds of times in 
the future. You can now switch to upper- and 
lowercase, if this applies. DOS will translate lowercase 
letters to uppercase. 

Typing Mistakes, Control Characters, 
and BREAK Key 

If you type a faulty command and press ), the CLI will 
respond with an error message - usually FILE DOES 
NOT EXlST-Jauhy-entry - and return the R prompt. If 
you want to correct a line before pressine return, 
simply press the DEL or RUBOUT key sequentially to 
erase characters from right to left. (On printer 
consoles, DEL or RUBOUT echoes a backarrow (_) or 
underscore (_) for each character erase.) You can erase 
an entire line by typing backslash (\) or SHIFT-L. 

To stop execution of any CLI command or utility 
program (except an editor), press the CTRL kev, hold 
it down, then press A. CTRL-A halts the command or 

program and returns the R prompt. 

You can interrupt output to your console at any time by 
typing CTRL-S. The output won't be lost; you "can 
continue it from the point of CTRL-S bv typing 
CTRL-Q. You can use CTRL-S and CTRL-Q 

intermittently to read a long file on a display console. 

If your computer has a programmed console (.'prompt), 
the BREAK key on the system console keyboard 
stops execution of all software. To continue with the 
program that was running, type P) (uppercase P, 
then )). We mention this here because, in the course 
of bringing up and running DOS, vou may 
inadvertently hit the BREAK key' If everything stops 
and the system console shows .', try typing P). 
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The Session 

If your system console has a display screen instead of a 
printer, you should record console dialog in the disk log 
file so that you can print and review it later. If the 
system console has a printer, it provides reviewable 
copy as you type; you don't need a disk log file and can 
proceed to the section called Master Directory Same. 

Log File 

With a display terminal, type 

LIST LOG. CM) 

If there is an old LOG. CM log file on the disk, the 
screen will display 

LOG.CM 

and a number and letter, then the R prompt. Preserve 

the old log file by typing 

RENAME LOG.CM LOGOLD CM1 
R 

Next, whether or not there was an old log file, type 
LOG/H) 

to create a new log file, open it, and start recording 
console dialog in it. Later, to close the log file vou'Il 
typeENDLOG ). 

Master Directory Name 

Next you should discover your master directory name, 

so type: 

MDIR) 

The CLI returns the master directory name, which 
varies with the type of disk you have. Generally it is 
either DEO, DPO, or DHO. We use Dxxio indicate the 
master directory name, so you should mentally 

substitute the name returned from MDIR] for Dxx'm 
this session. 



Creating Some Files 

The next step, naturally, is to create a file. The CLI 
offers several file-creating commands, and we choose 
CRAND: 

GRAND FtLEA) 
R 

Voila. You now have an empty disk file named FILEA. 
FILEA was an argument to your command; it told the 
CLI what to name the new file. Some CLI commands 

require arguments, others don't. 

You can verify FILEA's existence with the LIST 
command: 

LIST FILEA) 
FILEA. D 
R 

and remove FILEA with the DELETE command: 

DELETE/V FILEA) 
DELETED FILEA 
R 



The /V is a switch, which modifies the basic meaning of 
a command; here, it told the CLI to verify the deletion. 
Now, create a different version of FILEA: 

CRAND FILEA.MC) 
R 



Now there's an empty FILEA.MC on the disk. 
Normally, you'd use a text editor to put something in 
it, but you haven't reached Chapter 5 -- Creating and 
Editing Text -ytl. You can, however, insert text by 
transferring it directly from the console into 
FILEA.MC: 



XFER/A/B STTI FILEA.MC 

MESSAGE HELLO) 

CTRL-Z (Hold down CTRL key and press Z) 

R 
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The CTRL and Z keys won't echo as characters on the 
console. On a display terminal, the R prompt may leap 
to the top of the screen when you type CTRL-Z. If so, 
type CTRL-L to clear the screen and proceed with a 

clear screen. 

You've just transferred the CLI command MESSAGE 
and the text string HELLO into FILEA.MC. The 
XFER command transfers the contents of one file (the 
console input file, STTD to another file (disk file 
FILEA.MC). XFER requires two arguments; in this 
case, they were STTI and FILEA.MC. The /A switch 
specifies ASCII transfer; /B tells XFER to append to 
the existing file. If you omitted /B. XFER would try to 
create FILEA.MC, which would produce an error 
message because FILEA.MC already exists. 

Try to execute FILEA.MC: 

FILEA) 

HELLO 

R 



One problem with inserting text this way is that you 
can't edit. If you make a mistake and don't correct it 
before you terminate the line with a ), you must delete 
the file and rebuild it from the beginning. I laving made 
no mistakes, check the improved macro: 



FiLEA) 

HELLO 

HO W MA S Y BL OCKS A R E L EFT 
OS THIS DISK 7 

LEFT: 204 8 US ED: 408 

WHA TS THE CURREST DIRECTOR Y? 

D.xx 

R 



This DISK figure is for a double-density diskette. For a 
hard disk, it will be larger, for a single-density diskette, 
smaller. 



Your FILEA.MC is a CLI macro. The .MC extension 
tells the CLI to execute all commands within it. You 
can omit the .MC extension to executes file, but you 
must include it for all other commands that involve the 
file. Check FILEA. MC's statistics with LIST: 

'UST/E FILEA.MC) 

FILEA.MC 14 D 04/02/79 13:20 04/02/79 [000444/0 
R 

The /E switch tells the CLI to list every statistic about 
the file. These include byte-length 04), organization 
type (D means random), date and time created or last 
modified, date last opened, starting disk block address 
in octal, and use count. Obviously, the central four 
categories will differ for your own FILEA.MC. 

To check the file's contents, type: 

TYPE FILEA.MC) 
MESSAGE HELLO 
R 



FILEA.MC is much larger now, as you can see: 

LIST FILEA.MC) 
FILEA.MC 118 D 
R 



FILEA.MC now contains four MESSAGE commands, 
a DISK command, and a GDIR command. Each would 
work separately, but you've combined them. (Your 
own DISK figures may differ from those here). 



Proceed to create another macro: 

XFER/ASTTIFILEB) 
TYPE FILEA.MC) 
CTRL-Z 

R 



Now, you can add a little sophistication to FILEA.MC: 

XFER/A/B STTi FILEA.MC) 

MESSAGE HOW MANY BLOCKS ARE LEFT) 

MESSAGE ON THIS DISK? ;DISK) 

MESSAGE WHAT'S THE CURRENT DIRECTORY?) 

GDIR) 

CTRL-Z 

R 



Here, FILEB doesn't exist, so XFER will create it, and 
you can omit the /B switch. By doing so, you saved two 
steps, the CR AND FILEB and the /B switch, but 
you've been a little careless: 

FILEB) 

FILE DOES NOTEXIST:FlLEB. S V 

R 
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The CLI looked for FILEB.MC, then for the save file, 
FILEB.SV; finding neither, it returned the error 
message. To fix it. give FILEB the .MC extension: 

RENAME FILEB FILEB.MC) 
R 

FiLEB) 

MESSAGE HELLO 

MESS A GE HO W MA . V Y EL OCKS AREL EFT 

MESS A GE ON THIS DISK ?;DISK 



R 



You planned to have your second file type your first file 
and succeeded. Now, you'd like to compare the files, so 
you type LIST/E without an argument, as in Figure 
3-1. 



Your command told the CLI to list all nonpermanent 
files in the master directory; who knows how long the 
listing would have continued if you hadn't hit the 
CTRL-A keys to interrupt the command and return the 
CLI prompt. (Your own listing will differ from that 
above). The letters following the byte count indicate 
the file type and organization. 

There are some old friends shown in Figure 3-1: 
SYS.SV, CLI.SV (save files always end In .SV),and 
FILEA.MC. If you generated your own system, you'll 
recognize BOOT.SV. Unfortunately, FILEB.MC didn't 

show up. You could list the entire contents of directory 
DPO to find FILEB.MC, but there's a better way: create 
a directory for the two macro files. 



Creating Some Directories 

Proceed to create a directory: 

CDIR MACRODIR} 
R 

Now, to move the macros into the new directory. 

MOVE/V MACRODIR FILEA.MC FILEB MC) 

FILEA.MC 

FILEB.MC 

R 

The MOVE command copies the files into the new 
directory: the /V switch instructs the CLI to verify their 
names as they arrive. Now, the files are safely in " 
MACRODIR; you can make MACRODIR the current 
directory and then list the files in it: 

DIR MACRODIR) 

R 

LIST) 

FILEA.MC 118 

FILEB.MC 14 

R 



The DIR command makes MACRODIR the current 
directory. DIR also initializes a directory, if it hasn't 
been initialized. Initialization opens a directory for 
access to its files. The MOVE command - an exception 
to the rule - doesn't require initialization, but other 
commands do. Starting up DOS automatically initializes 
the master directory, but you must specifically initialize 
other directories to use them. DIR does this for you. 



LIST/E) 

SYS.SV 
DSKED.SV 
RLOR.SV 
CLI.OL 

BOOT.SV 
FILEA.MC 

CLI.SV 

CTRL-A 

INT 
R 



36864 


SD 


18<I32 


SD 


«608 


SO 


nim% 


C 


6656 


SD 


118 


D 


10752 


SD 



03/26/79 

03/29/78 
13/23/78 

18/05/78 
10/05/78 
0a/02/79 
10/05/78 



13.* 36 
16:18 

13:16 
1 n a 

23:03 
13.*2« 
10:14 



03/26/79 
03/29/78 
03/23/78 
03/30/79 
10/05/78 
04/02/79 
10/05/78 



£002707] 

[0016703 
[015741] 

£000366] 
[000522] 
C000«4«] 
[003«67] 



Figure 3- 1. Master Directory Listing 
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Now you can check the current directory with another 
useful command: 

GD1R} 

MAC ROD! R 
R 

For neatness, let's delete the original files in master 
directory Dxx. First, get back to the master directory: 

D1R%MD1R%) 
R 

%MDIR% is a CLI variable that contains the master 
directory name. You can use it in command lines just as 
you'd use DPO. 

Now to delete the original files: 

PELETE/V F1ELA.MC FILEB.MC) 
FILE DOES NOT EXIST: F1ELA.MC 
DELETED FILEB.MC 

R 

Typos are no-noes. 

DELETE/VFILEA) 

FILE DOES NOT EXIST: F1LEA 

R 

(sigh) 

DELETE/VF1LEA.MC) 
DELETED FILEA.MC 
R 

At this point, your disk looks like Figure 3-2; the 
current directory is Dxx. 



Whenever you create a directory, the CLI assigns the 
extension .DR to its name. The CLI also assigns 

different extensions to files after they have been 
assembled, compiled, or loaded. ,SV is another 
CLI-assigned extension. These extensions come in 
very handy when you want to access specific kinds of 
files. For example: 



L1STD-.DR) 

MACRODIR.DR 

R 



512 DY 



As explained in the Preface, the box represents a space; 
we use it only where a space isn't obvious in the format. 
The dash (-) is a template character, which in this case 
instructs the CLI to list ^//filenames that have the .DR 
extension. (Directories are also files.) Trv it with save 
files: 



USTD-.SV) 






SYS.SV 


39424 


SD 


DSKED.SV 


12288 


SD 


RLDR.SV 


4096 


SD 


CLI.SV 


10240 


SD 


CTRL-A 






INT 






R 







You could also have used the dash to list your .MC files 
on DPO, but you moved them instead, and they're 
probably better off in their own directory. You could 
also list all files without an extension by 'typing LIST -.), 
or files whose names began with a letter or number: 

LISTCS-.-) 

SYS.SV 39424 SD 

SED1T.SV 9216 SD 

SYS.OL 27648 C 






A i 



itMiil 



CTRL-A 

INT 

R 

Another template character is the asterisk, which 
means owecharacter. as opposed to the dash, which 
means from zero to ten characters. To list all five-letter 
filenames which begin with Fand have two-character 
extensions, you'd type: 



SO-01023 



Figure 3-2. Disk with Directory 



LISTZF- 



') 



FLOAD.SY 13072 SD 
FDUMF.SV 15360 SR 
R 



These files are the fast load and fast dump programs in 
the master directory. Note the absence of FILEA and 
FILEB, which are in M ACRODIR. 
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Templates work only with certain commands, in certain 
contexts. Don't be afraid to experiment with them 
(except DELETE); at worst, you'll get an error 

message. 

At this point, you can explore disk directories further 
Your disk has the master directory <Dxx) and one 
other directory (MACRODIR). Because vou've just 
started using your system, you don't have enough 
different kinds of Tiles to require another directory; but 
eventually you will want others. So, make sure Dxx, is 
the current directory, and create another directory. * 

D1R 3 MD!R%) 
R 

CDIR ALPHA) 
R 

L1STZ-.DR) 

MACRODIR. DR 512DY 
ALPHA.DR 5PDY 

R 

Now, you can proceed with your file hierarchy by 
giving the new directory a little file: 

DIR ALPHA) 
R 

XFER/ASTTI1NALPHA.MC) 

MESSAGE I'M A FILE IN DIRECTORY ALPHA ) 

CTRL-Z 

R 

DIR%MDIR%) 

R 

Your disk structure looks like Fiaure 3-3. The current 
directory is ALPHA. 






:'* >. 



The system allows you to access or execute any file 
simply by typing the directory name, a colon, and the 
file name (of course, you could alwavs DIR to the 

directory you wanted, then type the file name, but that 

requires an extra step). 

GDIR) 
Dxx 

R 

INALPHA) 

FIL E DOES SO T EX IS T: ISA LPHAS V 

R 

(True, in directory Dxx.) Try a directory specifier: 

ALPHA.1NALPHA) 

I'M A FILE IS DIRECTOR Y ALPHA 

R 

Eureka. The directory specifier (:) also works with most 
other CLI commands: 

USTALPHAdNALPHA.MC) 

ISALPHA.MC 39 

R 

TYPEALPHAdNALPHA.MC) 

MESS A GEl'MA FIL E IS DIR EC TOR Y ALPHA 

R 

Try it with FILEA.MC in MACRODIR: 

MACRODIR:FILEA) 

HELLO 

HO W MA S Y BL OCKS AREL EFT 

MESS A GE OS THIS DISK "> 

LEFT:2022 USED:434 

WHA T'S THE CUR REST DIRECTORY? 

Dxx 

R 

This example shows that GDIR always returns the 
current directory name (even though a file in another 
directory issues GDIR). 

There are some restrictions on directory specifiers; for 
example, they don't work with template characters: 

LISTMACROD1R.--.MC) 
R 






*iS*»hmMZs 
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Figure 3-3, Disk with Two Directories 



Now that you've tried directory specifiers, vou can use 
them to clarify the idea of initialization. The rules say 
that a directory must be initialized before we can access 
its files. Let's release MACRODIR (remove its 

initialization), and see. 

RELEASE MACRODIR) 

R 

MACRODIR.-FILEA) 

SO SUCH DIRECTOR Y: MACRODIRiFILEA 

R 
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So *e initialize MACRODIR again: 

INIT MACRODIR) 

R 

MACRODIRiFILEA} 

HELLO 



This is what a link eniry looks like: no byte count or file 
organization key letter. 

Now, when FILEB.MC searches current directory DPO 
for FILEA.MC the link entrv named FILEA.MC will 
point to MACRODIR: 



When you initialize, you can choose between two 
commands: INIT and DfR. Use INIT when you don't 

want to change the current directory, and DIR when 
you do. 

There are situations where directory specifiers appear 
useful, but are not. They don't help when the file 
specified needs another file and can't find it; for 
example: 

MACRODIR:FILEB) 

FIL E DOES SO T EX IS T; FIL EA .MC 

R 

Remember FILEB.MC? You wrote it to type 
FILEA.MC. and it did so; but now it cannot find 
FILEA.MC in the current directory, DPO. There are 
two ways to handle this: the obvious way, which 
requires deleting FILEB.MC and rewriting it with a 
directory specifier (MACR0D1R:FILEA.MC), and the 
challenging, interesting way. which involves creating a 
tin k entry to FILEA.MC. 

Link Entries 

At this point, you may be wondering how all this relates 
to useful processing. Well, we had to introduce the link 
entry somewhere; it can save you time and hundreds of 
blocks of disk space. When you begin to process data, 
you'll be linking from different directories to the big 
system utility assemblers or compilers in the master 
directory; this will allow you to assemble and compile 
files from any directory with almost no cost in extra 
disk space. 

A link entry is a filename whose sole function is to 

point to another filename in the same or in another 
directory. You can create a link entry with the LINK 

command and remove it with the UNLINK command; 
DOS'Tuse DELETE to remove a link because this will 
delete the file you linked to. 

GD1R) 
Dxx 

R 

LINK FILEA.MC MACRODIR:F!LEA.MC 
R 

LIST FILEA.MC] 

FIL EA . MC X I A CR ODER :FIL EA . MC 

R 



MACRODIR:FILE3) 

MESSAGE HELLO 

MESSAGE HOW MANY BLOCKS ARE LEFT 

MESS A GE OS THIS DISK 9 ;D/SK 



Your link entry allowed FILEB to find FILEA. If 

you're dubious, remove the link: 

UNLiNK/V FILEA.MC) 
US LIS K ED FILEA.MC 
R 
MACROD1R.-FILEB) 

FILE DOES SOT EXIST: FILEA.MC 
R 



Convinced? Recreate the link: 

LINK FILEA.MC MACR0DIR:F1LEA.MC) 

R 



You can use any name you want for a link, but if you 
forget it, your link will be useless. In this example, the 
link name had to be FILEA.MC because FILEB.MC 
would search for that name only. 



You'll use the same procedure to create all links. For 
example, the Macroassembler uses three files, which 
can require up to 250 disk blocks. You can link to the 

files from any directory, use the assembler, and use 
only a few bytes per link. 



You have now created files, two directories, and a link 
entry, and used the commands LOG, CRAND, LIST, 
DELETE, XFER, TYPE, MESSAGE, DISK, GDIR, 
RENAME, CTRL-A (not really a command, but an 
interrupt), CDIR, MOVE, INIT, RELEASE, LINK, 
and UNLINK. You've also used switches and the 
template characters, - and *. 



Your disk structure now looks like Figure 3-4. 
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Figure 3-4. Disk with Directories and a Link Entry 



Concluding the Session 

Before terminating the session, you might want to back 
up your disk material on a diskette. Take a fresh 
diskette, tape the write-protect hole, and insert it in the 
appropriate diskette drive. This drive is DEI if "Dxx" 
is DEO; otherwise it is DPI. If this copy diskette hasn't 
been initialized with DOSINIT, read the appropriate 
Chapter (7 or 8) of How to Generate Your DOS System, 
Backing Up Your Files. 



The dump procedure itself depends whether the master 
directory Dxx is (1) a double-density diskette or hard 
disk or (2) a single-density diskette. 



File Backup on a Double-density Diskette or 
Hard-disk System 

On this kind of system, you'll create facsimile backup 
directories on your backup diskette and MOVE the files 
into them. To do ALPHA, type the following 

commands: 

1N1T DE1 ) (for NOVA systems, substitute DPI for 
R DEI in this section) 

CDIRDE1:ALPHABU) 
R 

INITDE1:ALPHABU) 

R 

DIR ALPHA) 

R 

MOVE/VALPHABU) 

(names of files copied to directory ALPH ABU) 

R 
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ALPHADMP now contains copies of all nonpermanent 
files in ALPHA. Follow the same procedure for 
MACRODIR: 

CDIRDE1:MACROBU) 

R 

INITDE1:MACROBU) 

R 

DIR MACRODIR) 

R 

MOVE/VMACROBU) 



File Backup On Single-Density Diskettes ( 

For a single-density diskette, use the COPY command, 
which copies every directory and Tile to the destination 

diskette. Type: 

COPYDP0DP1) 

(pause) 

R 



(Never INIT or RELEASE the backup diskette for 
COPY.) 



Now, do the master directory: 

DIR Dxx) 

R 
MOVE/VDEO) 



Release the backup diskette: 
RELEASE DE1) 

In the future, perhaps daily, you can follow the same 
MOVE procedure for these and other directories you 
create under DOS. But in the future, you can use "the 
/R switch in the MOVE command. Normally, the CLi 
won't MOVE a file if its name already exists in the 
destination directory. But if you include the /R switch, 
the CLI will check both Tiles" creation dates and, if the 
file you want to move is newer, the CLI will delete the 
file in the destination directory and replace it with the 
newer version. The CLI will take no action on the 
destination file if the destination file is newer. 

You can couple the /R switch with an /A date switch 
for the move each day to ensure that the dump 
directory has the current versions of all files. For 
example, assume that (as shown in this chapter) the 
date is April 2. 1 979. At the end of tomorrow's session, 
10 back up ALPHA'S Tiles, you'd type: 

MOVE/V/R ALPHABU 4-3-79/A) 

R 

The CLI will then move any ALPHA files that had 
been created or changed on April 3rd into ALPHABU. 
If no files in ALPHA had been created or modified on 

April 3rd, no Tiles will be copied. 



Cleaning Up 

At this point, you've copied the entire diskette and file 
structure created during this session. If you want, you 
can now delete the new directories on the system disk 
and restore this disk to its original state with only the 
system files. If you don't want to delete these, skip to 
Shutting Down. To delete them, type: 

RELEASE ALPHA) 

R 

DELETE/V ALPHA.DR) 

DELETED ALPHA. DR 
RELEASE MACRODIR) 
R 
DELETE/V MACRODIR. DR) 

DELETED MACRODIR. DR 
R 



Using the Backup Diskette 

If something happens to one or more of the files or 
directories on your original master disk, you can simplv 
insert the backup in DEI or DPI and DIR to it. To 
replace a directory on the original, DELETE the 
original directory, recreate it with CDIR, INIT it, then 
get into the appropriate backup directory and MOVE ail 
Tiles to the newly-created directory in the original. To 
replace a file, simp!\ DIR to the backup directory and 
MOVE the file to the original directory. 

To make the diskette a true backup from which you can 
bootstrap a DOS system, you should install a bootstrap 
root on n via the BOOT BOOT command, as detailed in 
the appropriate After System Generation chapter in 
How to Generate Your DOS System. This will allow you to 
bring up DOS on the backup and rebuild the original 
disk if the original's file structure is badly damaeed. 
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Shutting Down 

At this point, if you opened fog file LOG. CM earlier, 
you might want to close it and print it. This will give you 
a hard-copy record of your dialog with the CLI. If you 
have a printing console connected to the second 

teletypewriter interface, type: 



ENDLOG) 

R 

XFER/ALOG.CM STT01) 



If you have a line printer, place it ON LINE and type: 

ENDLOG) 

R 

PRINT LOG. CM) 



You don't need a directory specifier to access LOG. CM 
(although a specifier would do no harm) because you 
started the log file in the current directory. For more on 
LOG and any other commands you've used, see the 
command in the CLI User's Manual. The log file is quite 
large by now (check it with LIST LOG.CVff; you might 
want to delete it. 



Now you can RELEASE the system. The RELEASE 
command removes a directory or device that INIT or 
DIR introduced to the system. In so doing, it updates 
the directory on disk. You can RELEASE^any directory 
from any directory -- including itself. To shut down the 
system. RELEASE the master directory: 

RELEASE %MDIR%] (or Dxx) 

The CLI and DOS will shut down; their final message 
will be: 

A I A S TER DE I ICE R EL EA SED 

You can now remove all diskettes from their drives and 
turn off the disk drives, computer, console and line 
printer (if any). Don't forget to write a label for the 
backup diskette (e.g., DOS SYSTEM BACKUP and the 
date) and apply the label. Never write on a diskette 
label after applying it -- unless you use a felt-tipped pen. 
After labeling, insert each diskette in its outer envelope 
and store it safely. 

Congratulations. You've just completed a session with 
DOS. This isn't a toddler's lesson; it includes most of 
the concepts and commands you'll use in your 
day-to-day interaction with DOS, and it provides a 
sound background for the intricacies of other CLI 
commands, DOS itself, and the next chapters. 

You can find details on certain CLI commands in 
Chapter 4; these are covered more deeply in the CLI 
User's Xfanuai You may feel ready to proceed to 
Chapter 5, which describes using the Superedit 
text-editing utility. 



End of Chapter 
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Chapter 4 
Commom CLI Commands 



The CLI is a powerful system utility that provides many 
commands, plus a macro facility so you can create stii! * 
more. As you saw in the last chapter, you can do a lot of 
work using just a small subset of CLI commands. 

In this chapter, we will describe CLI commands in 
greater detail. Most of these commands have features 
that are not described here. For a complete description 
of every command, see the RDOS1DOSCLI User's 
Manual. 

From the sample session, you have some sense of 
switches. We divide switches into two categories. Those 
that affect entire commands are called ?/oL/switches; 
those that affect one argument in the command are 
called /oca/switches. For example, say you want to copy 
all tiles with the extension .SR to directory XDIR except 
tiles whose names begin with M YPROG.'and vou want 
console verification. You would tvpe 



MOVE/VnXD[RD-.SRDMYPROG-/N) 

nll™^ ^J^^ whic ^ instructs the CLI to verify 

nit m ^ n 1S 3 bCal SW, ' lCh Which direcls the CU 
not to move files beginning with M YPROG 



Wherever you can use the template characters (- and *) 
in a command, we have noted this. 



If the CLI command you want to type is too long to fit 
on a single line, simply type an uparrow (SHIFT-6 or 
SHIFT-N) immediately before you type ). (Note that f 
works only in CLI commands. It does not function this 
way in other programs.) You can now continue the 
command on the next line. Naturally, you omit the f 
before the last } in the command line. For example, 



CRANDDf) 

XFILE} 

R 



You can also stack CLI commands on one line by 
typing a semicolon between them; e.g.. 



CRANDMYFILE;L1STMYFILE) 

MYFILE D 

R 
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BUILD 



( 



Build a file of filenames 



Format: 

BUILD newfilename filename [filename...] 

Build a new file (i.e., a list) of filenames in the current 
directory. The files need not exist, unless vou use the 
template characters as part of* filename. A Plena me can 
include a directory specifier if it doesn't include a 
template character. The original filenames will remain 
mtact. 

Global Switches: 

/A Include all filenames that have permanent and 
nonpermanent attributes (see CHATR command 
»n the CLI manual to set attributes). 

/K Do not include link entries. 



/N Do not include extensions to filen 
newfilename. 



ames in 



Template Characters 

Permitted 

Examples: 

BUILD ABC-.SR TEST-.) 

This command creates file ABC and writes two 
categories of filenames into it: those with the SR 
extension, and those which begin with TEST and have 
no extension. 

BUILDGMYTEXTZ-.TX3A-.-/N) 

This command creates M YTEXT and inserts the 
names of all files with the .TX extensions except 
filenames beginning with A into it. 



Local Switches: 

mm-dd-yy/A Include only the names of files created 
this date or after. Arguments mm 
(month) and dd (day) can be one or two 
digits. Date switches include all matching 
ImKs unless you include the global /K 
switch. 

mm-dd-yy/B Include only the names of files created 

beiore this date. 



name/N 



Do not include names that match name 
in newfilename. 



BUILD OUTPUTS-TEXT) 
PRINTD@OUTPUT@) 



This sequence produces file OUTPUT, * hich contains 
all filenames whose last four characters are TEXT and 
have no extensions; it then prints these files on the line 
printer. You can use BUILD to create a file E roup for 

Pr7nT^ W TT m K and • lhal d ° n ' 1 all ° W a te ^ mplate - ,ike 
PRINT above. (The sign instructs the CLI to use the 

contents of the file; it is further described in the CLI 
manual.) ««<-v,i.i 
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CDiR 



CPART 



Create a subdirectory (RDOS) or 
directory (DOS) 



Create a secondary partition (RDOS) 



Format: 

CDIR (sub)directoryname 

The new (sub)directory will receive the .DR extension. 

Switches: 

None 

Examples: 

DIRDP1} 

R 

CDIR BETH) 

DIR makes DPI the current directory; CDIR creates 
(sub)directory BETH.DR on DPI. CDIR DP1 :BETH is 
an equivalent command. 



Format: 

CPART partname blockcount 

Create the secondary partition named partname with 
the length specified in blockcount. A disk block is 512 
bytes or 256 words. The new partition will be a 
contiguous disk file and wilt receive the extension .DR. 

You cannot create a partition with less than 48 disk 
blocks. Also, if blockcount is not a multiple of 1 6, 
RDOS truncates it to the nearest lower multiple. 

Switches: 

None 

Examples: 

DIRDP4F) 

R 

CPART ALEPH 128) 

R 

The DIR command makes primary partition DP4F the 
current directory; CPART creates secondary partition 
ALEPH on DP4F. An equivalent command would be 
CPART DP4F:ALEPH 1 28). ALEPH is 1 28 disk blocks 
long and is logically distinct from primary partition 
DP4F. 
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GRAND 



DELETE 



Create a randomly organized file 



Delete one or more flies or directories 



Format: 

GRAND filename [filename...} 

Each random file receives the D (random file) attribute 
and a length of zero; it will grow as required during use. 

Switches: 

None 

Examples: 

GRAND RANDF1LE) 

This command creates RANDFILE in the current 
directory. 

GRAND ACCUFILE DP1 :GROWTHFILE) 

This command creates ACCUFILE in the current 
directory and GROWTHFILE in DPI. 



Format: 

DELETE filename [...filename] 

Delete the files in a directory having names given in the 
argument list. To remove a iink entry, you must use 
the UNLINK command. To delete a directory, 
RELEASE the directory, then type 
DELETE director/name. DR. 

Global Switches: 

/C Confirm each deletion. Each filename is repeated 
while the system waits for you to confirm the 
deletion by typing a carriage return. To prevent the 
deletion, press any key other than return. 

/L List deleted files on SLPT (overrides /V). 

/V List names of deleted files on the console. 
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DIR 



Local Switches: 

mm-dd-yy/A Delete only files created this date or 
after. Arguments mm (month) and dd 
(day) can be one or two digits. 

mm-dd-yy/B Delete only files created before this date. 

name/N Do not delete any files that match this 

name. 



Change the current directory 

Format: 

DIR directory [:subordinaie directory] 

At bootstrap time, the master directory becomes the 
current directory. The DiR command specifies another 
device or directory as the current device or directory. If 
necessary, this command will also initialize the device 
or directory. 



Template Characters: 

Permitted only when filename argument is in the 
current directory. 

Examples: 

DELETE/V LIMIT.-) 

This command deletes all files which have the name 
LIMIT and any extension (including none)- e g 
LLMIT.SR, LIMIT.RB, LIMIT.SV, and LIMIT. This 

also verifies their names on the console. 

DELETE/VDA"B) 

This command deletes all files with four-character 
filenames that begin with A, end with B, and have no 
extensions. It also verifies files deleted. 

DELETE/VDA-B) 

This command deletes all files whose names begin with 
A, end with B, and have no extensions. 

DELETE/Cu-.LS) 

A.LS:)* Delete file A. LS 

COM.LS:)* Delete COM.LS 
MAP.LS: Don't delete MAP.LS 

Confirm before deleting. The system asks for a 
confirmation of each deletion. When you confirm a 
deletion with a carriage return, the system echoes an 
asterisk ( ). Any other character echoes a carriage 
return. 6 



Switches: 

None 

Examples: 

DiR ACCTSDUE) 

This command makes directory ACCTSDUE, on the 
current partition or disk, the current directory. 

DIR DP1:DEF) 

This command makes directory DEF, on DPI, the 
current directory. 
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DISK 



DUMP 



List the number of disk blocks used and 
remaining 

Format: 

DISK 

This command returns the decimal number of blocks 
used and the number of blocks left on the current 
partition or diskette. If the current directory is a 
Subdirectory, DISK reports on its parent partition. 

Switches: 

None 

Examples: 

DISK) 

LEFT:2048 USED:400 

The response indicates that 2048 out of a total of 2448 
blocks are still available for use. The figure could 
pertain to a secondary partition or a double-density 
diskette. 



Copy one or more files to an output file 

Format: 

DUMP outputfiiename [filename...] 

Use this command to copy files from the current 
directory onto a given file or device outputfiiename. If 
you specify filename (with or without template), only 
matching files are dumped. If you omli filename, all 
nonpermanent files in the current directory are ' 
dumped; this includes subordinate directories, if any. 

Use LOAD to restore DUMPed files to the current 
directory. 



Global Switches: 

/A Dump all files, permanent and nonpermanent. 
/K Do not dump links. 

A. List the dumped files on SLPT (overrides /V). 
/V Verify DUMPed filenames on the console. 
Local Switches: 

mm-dd-yy/A Dump only files created this date or after. 
Arguments mm (month) and dd (day) 
can be one or two digits. Date switches 
dump all matching links unless vou 
include global /K switch. 

mm-dd-yy/B Dump only files created before this date. 

name/N Don't dump files that match name. 
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ENDLOG 



Close the LOG file 



Template Characters: 

Permitted only when filename argument is in the 
current directory. 

Examples: 

DUMP/A/L MTO:0 2-20-79/A) 

This dumps all permanent and nonpermanent disk files 
created on or after February 20, 1 979 onto file (the 
first file) of magnetic tape unit number 0. It also sends a 
listing to the line printer. You can then save this tape 
file as a backup for the disk. 

CUMP/A/LDP4:SQURCE-.SR 7-14-77/A) 

This tells the system to dump all files with the .SR 
extension created on or after July 14, 1977 to file 
SOURCE on DP4, and to send a listing of filenames to 
the printer. 

DUMP/VZMTO:0 -.-C-.RB/NGTEMP.DR 

Dump all nonpermanent files in the current directory 
(except .RB files) and directory TEMP and all its files, 
to file Oof the tape MTO. 



Format: 

ENDLOG [password I 

Close the log file which you opened by a previous LOG 
command. You must close this file before vou can 
TYPE, PRINT or DELETE it. If the previous LOG 
command included a password argument, you must use 
the password with the ENDLOG command. 

This command. ENDLOG password, appears in the loe 
file. 

Switches: 

None 

Examples: 

ENDLOG GSTONE) 

The password GSTONE is used since it was specified 
when the log file was last opened. 

Note that you must type the full name of the log file to 
PRINT or DELETE it; this name is LOG. CM. " 
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GDiR 



INIT 



Display the current directory name 

Format: 

GDIR 

Switches: 

None 

Examples: 

GDIR) 
MASH ATT AS 

MANHATTAN is the current directory. 



Initialize a directory or tape drive 



Format: 

iN[T itape drive \ 

(directory [-.subordinate direaorvj) 

By initializing a device or directory, you introduce it to 
the operating system; before the introduction, all of its 
files are inaccessible. 

After you INIT a directory or tape drive you can access 
all files within it; you can use the colon specifier (e.g., 
MYDIR:FILEA) at will. All files on the initialized tape 
unit, directory, or diskette are available until you 
release (RELEASE command) the device or directory. 

Global Switches: 



/F 



Full initialization of a tape drive rewinds the tape 
and writes two EOF's at its beginning, effectively- 
erasing the tape. On a disk, INIT/F builds a new file 
directory and free storage map, effectively 
destroying all existing files. Alwavs think twice 
before typing INIT/F to anything. 



Local Switches: 

None 

Examples: 

INITDP4 

This command initializes the disk in DP4. 
1NITMT1) 

This command initializes tape drive MT1 and enables 
access to the tape unit. 

INIT DP1. ABC) 

All files in directories DPI and ABC will now be 
accessible, provided you direct file access with explicit 
directory specifiers. 
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LINK 



Create a link to a fife in another directory 



Format: 

( resfilename/2 



LINK < resf ' lename/2 \ 

\ linkentryname [directory specif er:] resfUe name j 



resfilename is the file you're linking to. If your link 
entry will have the same name as the resolution file 
(resfilename), and resfilename is in the current 
directory's parent directory, you can create your link 
with the first command format (the local 12 switch 
specifies the same filename). Linkentryname will always 
be created in the current directory unless you specify 
another directory. 



If the resolution file is not in the current directory's 

£n.m-° r r, y ° UI " Hnk name wi " differ from the 

l,! on " e s ' use ^ second command format. The 

directory" resfilename ma - v exist in an - v initialized 



Global Switches: 

None 



Local Switches: 

finkentryname/2 

nam^lnTinkenTrvn" 16 *? 3 resoIution r 'le of the same 
Partition is the disk S S P3rent parlh, ' on - The P arent 
the current directo ° r Secondar - v Partition that contains 



Examples: 

MDIR) 

DEO 

R 

DIRMYDIR) 

R 

LINKEDIT.SV/2) 

The master directory is DEO. and it contains 
(sub)directory MYDIR. DEO is M YDIR's parent 
directory, so the LINK EDIT.SV/2 links to EDIT SV 
(the Text Editor) in directory DEO. Typing LINK 
EDIT.SV/2 is easier than typing LINK EDIT.SV 
DEO:EDIT.SV, which would have the same effect. 

DIRDP1) 

LINK NSPEED.SV DPOrNSPEED SV) 

LINK SPEED.ER DPO:SPEED.ER) 

I h 4 C0 n ™; ? nd Creates two link entrie s n ^ed 
nn npn r? ^ SPEED - ER in DP 1 to the editor files 
^JinJ^J^l 18 anyone in ^'rectory DPI to use 
the NOVA (NSPEED) Supereditor. 

LINK ASM. SVDZO:ASM.SV) 

This command creates a link entry named ASM.SV in 

dtctoTy 6 DZ0. eCtOry t0 thS SXtended 3SSembler in 

DIRFORT4) 

LINK FORT.SV DP0:FORT SV) 

LINKF1V.SVDP0:FIVSV}' 

LINK ASM.SV DPO:ASM.SV) 

These commands create link entries to the FORTRAN 
V compiler files and to the extended assembler which 
the compiler needs) in directory FORT4. 
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LIST 



List fife directory information 



Format: 

LiST [directory:] [filename. . .] 

For each file, listed information includes the filename 
size, and organization type (except for link entries) 
You can specify other data with global switches. 

If you omit an argument, the system lists all 
nonpermanent files and link entries in the current 

directory. 

The link access attributes, if any, are preceded bv a 
slash. For link entries, the list includes the link name 
the resolution-file name, and the directory specifier (if 
any) given when the link was created. A commercial at 
sign (<&) indicates that the resolution file is on the 
parent partition or diskette. The following link 
directory lists common file attributes (or link access 
attributes) and their meanings: 



Letter Meaning 



file; cannot be deleted 



or 



S 

w 

A 



Permanent 

renamed. 

Save file, i.e.; executable program. 

Write-protected file; cannot be modified 

Attribute-protected file whose attributes 

cannot be changed. The A attribute cannot be 

removed. 



The following is a list of file character 
meanings: 

Letter Meaning 



isticsand their 



Space, sequential file organization. 
Random file organization. 
Contiguous file organization. 
This file is a partition (RDOS only). 

This file is a directory. 



Global Switches: 

/A List all files within the current directory, both 
permanent and nonpermanent. 

/C List the creation time. 

/E List every category of file information. 

/L Output listing on line printer. 

/K Do not list links. 

/N List links only. 

/O List date file last opened (month/day/year). 

/S Sort the output listing alphabetically by filename. 



Local Switches: 

mm-dd-yy/A List files created this date or after. 
Arguments mm (month) and dd (day) 
can be one or two digits. Date switches 
list all matching links unless you include 
the global /K switch. 

mm-dd-yy/B List files created before this date. 

name/N Do not fist files that match this name. 



Template Characters: 

Permitted only when t he. filename argument is in the 
current directory. 
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LIST (continued) 



LOAD 



Examples: 

UST/E/A) 

This command lists every type of information on ail 
files and link entries in the current directory. A typical 
line of information would look like this: 

FLl.SV 8160 SD 03/23/79 13:56 03/23/79 [000164/0 

In this example, FLl.SV is the filename; it consists of 
8. 1 60 bytes, is a randomly organized save file, was 
created (or modified) at 1:56 p.m. on the 23rd day of 
March 1 979, was last opened on that same date, has a 
starting logical block address of 164 g , and has a file use 
count of zero. 

Typical lines describing link entries would look like 
this: 

ASM.Sl' DP0:ASM.SV 

The link entry name is ASM.SV; the link was created to 
resolution file ASM.SV on DPO. 

EDIT. SI W:ED1T.SV 

In this example, the link entry name is EDIT.SV and 

the resolution file was defined to have the same name 
and to reside on the parent partition or diskette. 

UST/K/SZ-.SVG5-2-79/A) 

List all nonpermanent save files (.SV extension) 
created after May I. 1979 and sort the list 
alphabetically. This will not list links and output will go 
to the console. 

L1ST/AZ-TEXT-.SRC-TEXT1 -.-/N) 

List all files whose names include the letters TEXT, 
with the extension .SR. except those filenames which 
include TEXT!. 



Load dumped file*. 

Format: 

LOAD mputfilename [filename...] 

Load a previously-dumped file from wpurfilenameini 
the current directory. If you omit filenames and 
switches, all nonpermanent files in the input file are 
loaded. With global switches, you can select filenamei 
for LOADing, or you can choose simply to list on the 
console or printer the filenames in the input file. 

The LOAD command can load only those files that 
were previously DUMPed. Files you want to load must 
bear different names from files in the current directory 
(unless you specify the /N. /O or /R switches). 

Global Switches: 

/A Load all files, including permanent files. 

/K Do not load link entries. 

/L List loaded filenames on the line printer 
(Overrides /V switch and listing by /N.) 

/N Do not load files; output the filenames to the 
console. 

/O Delete current file if it exists and replace with file 
being loaded that has the same name. 

/R Select most recent version. If a file in the curreni 
directory has the same name as a file in the 
inputfile, check both files' creation dates. If the 
version in the inputfile is newer, delete the version 
in the current directory and replace it with the 
newer one in the inputfile. If the version in the 
inputfile is not newer, take no action. 

/V Verify the load by listing filenames loaded on the 
console. Filenames in a directory are listed before 
the directory name. 
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LOAD (continued) 



LOG 



Local Switches: 

mm-dd-yy/A Load only files created this date or after. 
Arguments mm and dd can be one or two 
digits. Date switches load all links unless 
you include the global /K switch. 

mm-dd-yy/B Load only files created before this date. 
name/N Don't load files that match name. 

Template Characters: 

Permitted when the file sought is not part of a directory 
m the mputfile. For example, assume that M YFILE SR 

a u d r^! Y w I n LE ' SV Were in direct °rv SUBDIR on DPO If 
the DUMP sequence had been DIP, SUBDIR- DUMP 
MT0:O), then LOAD MTO:0 MYF1LE-.-) would work But 

lJ.vcn U r mP Sequence had besn DUMP MTO:0). then the 
MYHLE template wouldn't work. 

Examples: 

LOADMT0:1) 

This command loads onto disk all previously dumped 
nonpermanent files on file 1 of the tape on MTO. 
Filename, length, and attributes are entered in the 
current directory's file directory. 

LOAD/LlZDP4:DUMP0307-.SVG3-12-79/AGTEST-.-/N) 

This loads from file DP4:DUMP0307 all files with the 
■SV extension (except files whose names begin with the 
characters TEST and files created before March 12 
1979), and lists them on the line printer. 



Start recording m the log file 

Format: 

LOG {pass word} [directory 10} 

The log file records ail CLI dialog that appears on the 
console in a file named LOG. CM in the current 
directory. You cannot examine, print, or delete the log 
file while it is open. You can close it with the ENDLOG 
command. Releasing the master device or giving the 
BOOT command also closes it. LOG. CM records dialog 
cumulatively; after anyone types LOG, it will append ~ 
new dialog to the old. To start a new loe file in the 
current directory, RENAME or DELETE the old one 
then type LOG). 

You can use a password to prevent the log file from 
being closed inadvertently. The password is an optional 
argument, up to 10 alphanumeric characters in length 
If you specify password, the same password must be 
used in the ENDLOG command to close LOG.CM. 

The directory argument indicates a destination for the 

log file other than the current directory. You must 
initialize the directory before using its name. 

Global Switch: 

/H Place a header, containing directory and date 
information, at the beginning of the log'file. 

Local Switches: 

directory/O Output the log file to directory. 

Examples: 

LOG/HGSTONE) 

This command outputs ail CLI dialog to the file 
LOG.CM in the current directory. The password is 
GSTONE. 
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MOVE 



Copy files to any directory 



Format: 

MOVE destination-direc?oryname [filename., 
[oldJllename/S new filename]. . . 



•if) 



This command will copy a given file or files in the 
current directory to another directory. Filename cannot 
be a directory. If you omit filenames and switches, ail 
nonpermanent files in the current directory are moved. 

Global Switches: 

/A Move all files, including permanent files. 

/D Delete original files after MOVE. 

/K Do not move links. 

/L List moved filenames on the line printer. 

/R Select most recent version. If a file in the 
destination-directory has the same name as a file to 
be MOVEd, check both files' creation dates. If the 
version to be MOVEd is newer, delete the version 
in the destination-directory and replace it with the 
newer version. If the version to be MOVEd is not 
newer, take no action. 

N Verify MOVEd filenames on the console. 



Local Switches: 

mm-dd-yy/A 



Move any file created or 
modified this date or after. 
Arguments mm (month) and dd 
(day) may be one or two digits. 
Date switches move all matching 
links unless you include the 
global /K switch. 



mm-dd-yy/B 



name/'N 



Move any fife created or 
modified before this date. 

Do not move files that match 
name. 



oldname/S newname Assign newname to the 
preceding file but retain its 
oldname in the current directory. 



Template Characters: 

Permitted. 

Examples: 

MOVE/D/KCMYDIRG-.SR) 

This command moves all nonpermanent files in the 
current directory with .SR extension (except link 
entries) into destination-directory MYDIR, and deletes 
the original files after the transfer. 

MOVE/A ACCTSDUEC-.-C3/1/79/B) 

This command moves to directory ACCTSDUE all 
files created or modified before March 1, 1979. 

DIR MYDIR} 

MOVE/V %GD!R% F1LEA/S FILEA1 ) 

FILE A I 

This command copies a file, under a different name, in 
the current directory. By doing this when you plan 
extensive changes to a file, you preserve a backup 
version. In this case, FILEA 1 is a backup version of 
FILEA. 
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PRINT 



RELEASE 



Print a file on the line printer 

Format: 

PRINT filename f. . filename] 

The source files you wish to print may come from any 
device. 

Switches: 

None 

Examples: 

PRINT FOO.SR DP4:COM.SR EXT.SR) 

This command prints source Tiles FOO.SR, COM.SR in 
DP4, and EXT.SR on the line printer. 

PRINT ACCTSDUE.-JONES.CO) 

This prints Hie JONES. CO in directory ACCTSDUE. 



Release a directory or tape drive from the 
system 



Format: 

RELEASE fe C l, 0ry \ 
(tape drive) 

RELEASEing a directory releases all subordinate 
directories. When you RELEASE a mag tape unit, the 
tape is automatically rewound. After release, a 
directory or device is closed to access until you initialize 
it with an INIT or DIR command. Be sure to release a 
disk before physically removing it. By releasing a 
directory, you release all subordinate directories in it; a 
release of the master directory releases everything in 
the system, including tape transports. 

Switches: 

None 



Examples: 

RELEASE DP1) 
R 



This command releases DP] and all its directories. DPI 
was not the master device. 

RELEASE DPOF) 

MASTER DEVICE RELEASED 

This releases DPOF, which was the master device. 
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RENAME 



TYPE 



Rename a file 



Type a file on the system console 



Format: 

RENAME oldname newname [old name newname] ... 

Rename a file in the current directory. You can rename 
any nonpermanent file that is not open, but note that 
some system utilities (e.g., the assemblers or the 
FORTRAN compiler) will not work if you RENAME 
them. No save (program) file can execute without the 
.SV extension. 



Format: 

TYPE \Wename filename... 

Copy an ASCII file or files on the console. The source 
files may come from any device. 

Switches: 

None 



Switches: 

None 

Examples: 

RENAME LOG. CM LOGOLD.CM) 
R 

Rename the current log file LOGOLD.CM. The log file 
must have been closed via ENDLOG before you can 
RENAME it. 



Examples: 

TYPE A.SR B.SR DP1 :XX.SR) 



This command displays or types the following disk files 
on the program console: A.SR and B.SR in the current 
directory, and source file XX.SRon DPI. 



RENAME FILEBFILEB.MC) 
R 

Give FILEB the .MC extension so that the CLI can 
execute it as a macro file. 
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UNLINK 



XFER 



Remove a link entry 

Format: 

UNLINK linkname [...linkname] 

Unlink files by removing one or more link entrynames. 
This does not affect the resolution file. 

Global Switches: 

/C Confirm each removal. The system displays each 
fink name on the console, and waits for you to 
confirm the deletion by typing a carriage return. 
Type any key other than return to retain the link. 

/L List the removed links on the tine printer 
(overrides /V). 

N Verify each link entry removed. 

Template Characters: 

Permitted only when the linkname argument is in the 

current directory. 

Examples: 

UNL1NK/CGTEST.-} 

This command asks for a confirmation before each link 
entry is removed: 

TEST.SR)* Link TEST.SR is removed 
TEST.RB)* Link TEST.RB is removed 
TEST.SV% Link TEST.SV is not removed 



Copy the contents of a file into another 
file 



Format: 

XFER sourcefile destmationfile 

XFER can transfer a file on any device to another file 
on any other device. If destmationfile does not exist, 
XFER creates it. XFER differs from MOVE and 
DUMP in that it transfers only ihe file contents, not the 
name, creation date, or other file directory 
information. MOVE and DUMP do copy this 
information. Thus, you cannot XFER a file that has 
been DUMPed; you must LOAD it first. To copy a 
binary file (.RB or .SV extension), use the MOVE 
command. XFER will work for such tiles only if you 
execute certain steps afterward as described in the CLI 
manual, XFER command. 

You can XFER console input directly to a file, as shown 
in Chapters 2 and 3. 

Global Switches: 

By default, files are transferred without alteration. 
There are two global switches: 

/A ASCII transfer. Transfer the file line by line taking 
appropriate read/write action, such as inserting line 
feeds after each carriage return when transfer is 
from disk to line printer. 

/B Append the source file to the end of the destination 
file. (Required to append to an existing file.) 

Examples: 

XFERSPTRQ) 

This command transfers the file in the paper tape 
reader to a disk file named Q. 

XFER DPO:MYFfLE DP1 :MYF!LE) 

This copies the contents of M YF1LE in directory DPO 
under the name M YFILE file in DPI. 

See Chapter 2 or 3 or the CLI manual for other 
examples. 
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The Next Steps 

If you'll be working exclusively in BASIC, skip all the 

way to Chapter 7; you don't need the next two 
chapters. 

To code in another high-level language, you'll use a 
text editor program (described in Chapter 5), a 
compiler, then another utility to make the compiled 
code executable. Chapter 6 covers the compiling and 
processing steps for a FORTRAN IV program; steps 



for other languages are similar. For the precise details, 
of course, see the language reference manual for 
your compiler. 



If you're an assembly language programmer, you'll 
follow the same procedure as the FORTRAN 
programmer, except that you'll use an assembler 
instead of a compiler. You'll need Superedit (Chapter 
5), then the assembly language information in 
Chapters 8 and 9. 



End of Chapter 
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Chapter 5 
Creating and Editing Text 



You received two different editor utilities with your 
system: the text editor (EDIT) and the Supereditor. 
Superedit, the topic of this chapter, is the more 
advanced editor and is much handier than the XFER/A 
command you used in the last chapter. Within this 
chapter, we explain enough Supereditor features to let 
you use it. A complete description of the editor is 
outside the scope of this book; you can find a complete 
description in the Superedit Text Editor User's Manual 
(R DOS/DOS). 

It's sound practice, especially for a new user, to save a 
backup copy of each text file under a different name. 

Superedit Features 

The editor is a utility program which you evoke by a 
CLI command, but its commands bear no relation to 
the CLTs. Superedit lets you create and modify files 
containing upper- and lowercase ASCII text. During 
editing you can change, delete, search for, or insert 
single text characters, lines of text, or large portions of 
whole files. The editor is string-oriented. This means 
that its commands work with character sequences, 
which need not be complete lines. A line of text is a 
string of characters terminated by a carriage return. 
You can change or search for character combinations 
without knowing where they are. 

Superedit maintains a character pointer (CP), which 
indicates the current editing position in the file. It also 
provides a command to show you where the CP is; but 
for the most part, you simply keep a mental note of the 
pointer's position. You change the CP's position by 
executing edit commands. 2L, for example, moves the 
CPdown to the start of the second line beyond its 
current position. 



executing edit commands. 2L, for example, moves the 
CP down to the start of the second line beyond its 
current position. 



You can enter two kinds of input when you edit: editor 
commands and text you want in your file. When you 
are inserting new text, your Superedit command, 
which may include many lines, will include text you 
want inserted. 



When it is ready to execute a command, Superedit 
types an exclamation point (!) prompt character. After 
you see this prompt, you can type in one or more 
editing commands. You can enter two or more 
commands on one line by typing an ESC character 
between each command; you terminate the entire 
command line by typing ESC twice. When you type 
ESC, Superedit echoes a dollar sign on your screen; 
obviously, ESC ESC appears as two consecutive dollar 
signs. Superedit executes the commands in a multiple 
command entry sequentially, from left to right. If you 
enter an incorrect command anywhere in a multiple 
command line. Superedit informs you of the error, 
then ignores the remainder of the command line; that 
is, it processes only those commands to the left of the 
invalid command. 



Note: Although Superedit accepts both upper- and 
lowercase characters, the FORTRAN 
compiler and assemblers do not, except in 
text or comment strings. Thus, for all text 
you intend to compile or assemble, you must 
enter letters in uppercase, except for 
comment or text strings. 
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Superedit Command Summary 

The editor commands we will explain are: 

Command Operation 

C Change a string of text to another string. 



H 

t 

J 

K 

L 

M 

S 

T 

UE 

US 



Halt the Superedit program and return lo 
theCLI. 

Insert new text. 

Jump to the beginning of the edit buffer. 

Kill (delete) one or more lines of text. 

Move to the beginning of a line. 

Move n number of characters. 

Search for a string of text. 

Type one or more tines. 

Close the file, include all updates and write 
it to disk. 

Close the file, including all updates, and 
write it to disk; save the original file under 
the original filename with the .BU 
extension. 



The edit buffer is an area of the computer's memory 
where Superedit works on your file during the editing 
process. The commands you type change the buffer; 
the edited file isn't written to disk until you type UE. 



invoking the Editor 

To begin an editing session, get into the directory that 
holds Superedit. This is often the master directory, but 

you can check in any directory. DIR to it and type: 

L1STC-SPEED.SV) 

After you have found it, type: 
HSPEED filename ) 
on a NOVA computer; or 
SPEED filename) 

on an ECLIPSE computer. 



filename is the name of the Hie you want to edit. If 
filename already exists, Superedit will copy it into the 
edit buffer. If filename does not exist, Superedit will 
create a file for you, and you'll begin editing with an 
empty edit buffer. In the latter case, Superedit will give 
you the message: 

CREATING SEW FILE 

If you want to use Superedit from a directory that does 
not hold its files, DIR to the directory and type: 



LINK 



LINK 



,iSPEED.SVdestdir:SPEED.SV \ , 
)NSPEED.SVdes?dir:NSPEED.SVf j 

SPEED. ER destdtr:SPEED,ER) 



The destdir is the name of the directory that holds the 
Superedit files -- often the master directory, Dxx or 

%MDIR%. 

To illustrate each Superedit command, we'll create and 
edit a FORTRAN source program that calculates 
mortgage payments. We begin by entering the CLI 
command that executes the editor program: 

( SPEED ( M ORTGAGE.FR) 

At this point, Superedit replies: 
CREATING NEW FILE 



The exclamation point is the Superedit prompt; it 
means that we can start keying in commands. We 
received the message CREATING NEW FILE because 

MORTGAGE.FR did not exist before we gave the 
command. 

Typing Mistakes 

Often, as you are typing a Superedit command, and 
before you type ESC ESC, you'll notice that you made 
a mistake. Superedit gives you three easy ways to 
correct any mistake: 

• DEL or RUBOUT 

• CTRL-X 

• CTRL-A 

Strike the DEL or RUBOUT key to backspace and 

delete the previous character. Superedit will echo each 
character rubbed out. You can do this repeatedly to 
delete some or all of your command to the beginning of 
the current line. (DEL or RUBOUT will not delete the 
prompt character.) 
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If you want to delete the entire current line, simply type 
CT RL-X. This is equivalent to typing DEL or 
RUBOUT back to the beginning of the line. CTRL-X 
deletes the last line only. 

Finally, if you want to cancel a command that Superedit 
is executing (after you've type ESC ESC), type 
CTRL-A. With the commands we've described here, 
however, you will usually not be quick enough to stop 
the whole command from being executed. 

A Note of Caution 

Superedit is a powerful editor -- practically a 
text-processing language -- but its power and speed can 
sometimes make life difficult for a novice user. Until 
you learn it well, you should update your file often, 
saving a backup version with the US and H commands 
(USSHSS) to minimize lost effort. If text seems to have 
vanished from the edit buffer after a command, type 
USSHS to update the file and save the original version, 
then examine both the current and original versions 
with either Superedit or the CLI TYPE command and 
work with the one you want. The US and H commands 
are detailed later in this chapter. 

Insert New Text (I) 

When you evoke Superedit, it reads some or all of your 
file into its buffer (if the file already exists), or simply 
starts with a clear buffer. In either case, its CP 
(character pointer) always points to the first position in 
the buffer. Since you have just created a file, there is 
nothing to edit and you can start by inserting lines of 
source code. 

ItabREALINT, ITD, LB) 

StabTYPE "ENTER AMOUNT, RATER, YEARS") 

tabTYPE "AND, FOR SUMMARY OR 1 FOR") 

$$ 

tab represents pressing the CTRL and I keys to produce 
a tab. 

After each insertion, the CP points after the last 
inserted character. This lets you repeat insert 
commands in the same order that you would type 
words or lines of text on a typewriter. In the text above, 
we could have typed the text between quotes in 
lowercase, however, the compiler requires the REAL 
statement in uppercase.) 



Generally, you should not insert more than ten tines of 
text in one I command. It's sound practice to end each 
Insert with SS after typing several lines, then continue 
inserting with a new I command. 

lump CP to the Beginning of the Buffer (J) 

At any time in the editing process you can move the CP 
to the start of the buffer; simply key in the J command. 
You can also use the L command to move the CP from 
one line to another, but J gets you to the start of the 
buffer immediately. 



Examine Some Lines in Your File (T) 

It's pretty good practice to review each addition or 
change after you make it, so after every change you 
should type the T command. There are three variations 
of this command, and none of them moves the CP: 



O.nT 



nT 



Type the buffer from the beginning to 
character n. To type the entire buffer, simply 
insert a number sign before T; i.e., # T. 

Starting at the current CP, type the next or 
previous n lines of the buffer, n is positive 
(forward) unless you precede it with a minus 
sign. 

-mTnT Type text from m lines backward to n lines 
forward, to show the text surrounding the CP. 

T Type the current line and show where the CP 

is. Superedit uses the 3-character combination 
({) to show where the CP is. 



The command 

2TSS 

types the current line and the next line, while 

-2TSS 

tvpes the two previous lines. In the example above, the 
string JS3TSS displays the three lines typed. 



089-000022-01 



5-3 



Search for a Character String (S) 

One of the most useful Superedh commands is the S 
command. This command lets you find character 
combinations or strings. A string Is a sequence of any 
number of characters (including lowercase letters and 
invisible characters like )). When you use the S 
command, you move the CP forward through your 
file to the character position immediately after 
some character string. Thus: 

JSSTYPED 

moves to the start of the buffer and searches for the 
string "TYPE □". If we added the T command to the 
command string: 

JSSTYPEDSTSS 

Superedit would type the string and show the CP: 

5TYPE (J) "ESTER AMOUST.RATER, YEARS" 



In a search or change command, you must type 
precisely the string you want. If, for example, you 
carelessly insert two spaces in the search command. 
Superedit will not find the string and will display an 
error message. 

USSTYPEDZSTSS 

ER ROR: USS UCCESSFL L SEA R CH 

STYPEcnST 



When a command fails, Superedit types it back after 

the error message. 

You'd get the same message if the CP was beyond the 
text siring you wanted and you specified a sea'rch 
without repositioning the CP: 

US REALSTSS 

REAL {]) 1ST, ITD, LB 

iSREALSTSS 

ERROR: UNSUCCESSFUL SEARCH 

SREALSTSS 



When the editor cannot find a siring, it positions the 
CP at the start of the buffer. 



Change Text in Your File (C) 

When you key in a C command, you specify the string 
you want to change and the new string that you want to 
take its place. Separate these two arguments with an 
ESC character. The command resembles S in that it 
searches for a string to change; but C changes 
characters - thus you must be careful to specify the 
exact combination of characters you want to change, or 
you may end up changing a string that you wanted to 
leave intact. You can also use the CstringSS command 
to delete a string. 

When you inserted text with the I command, you tvped 
RATER instead of RATE. Suppose you back up the CP to 
the beginning of the buffer (using the J command) and 
tell Superedit to change TER to TE: 

USCTERSTESTSS (Start at beginning of buffer; 
change the first occurrence of 
"TER" to "TE", type line.) 

then you end up with a source line that reads 
5TYPE"ESTE AMOUST.RATER, YEARS" 

So, to correct the mistake and verify the correction, 

type: 

UCENTEZSENTERSTSS 

5 TYPE "ESTER (]) AMOUNT, RATER, YEARS" 

! 

Then fix RATER, being more specific about the 

change: 

•CRATERSRATESTSS 

5 TYPE "ESTER AMOUST, RATE (p. YEARS" 

! 

This changes RATER to RATE, the chanue vou 
wanted to make. 

You could have done this a different way, by making 
sure the CP was positioned properly with the S 
command: 

USSTERSTSS 

5 TYPE "ESTER (p AMOUSTJIATER YEARS" 

iCTERSTESTSS 

5 TYPE -ESTER AMOUSTRA TE (p. YEARS" 
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Set the CP at the Start of a New Line (L) 

Often you may want to set the CP several lines forward 
or backward from its current position. You use the L 
command to do this, and it has two variations: 

L Set the CP to the beginning of the current line. 

nl Set the CP to the start of a different line. If n is 
positive, the CP moves n lines forward from the 
current line. If you precede it with a minus sign. 
the CP moves n lines backward. 

L moves the CP to the start of the current line. 2L 
moves the CP to the start of the second line down from 
the current line. 

Again, you can use the T command to check the CP 
position: 

USTSS 

(\) REAL INT, ITD. LB 

•LSTS2LSTSS 

(\) REAL INT ITD. LB 

(!) TYPE "AND. FOR SLAIUAR YOR I FOR " 



The first command line starts at the beginning of the 
buffer and types the first line. The second command 
line moves the CP to the beginning of the line, types 
the line, then moves the CP two lines forward and 
types that line. 

Move the CP (M) 

The M command, format nM, moves the CP backwards 
or forwards by n number of characters. To move the 
CP to the left, make n negative: e.g., -2M. To move it 
to the right, use a positive number; e.g., 2M. 
Generally, you'll use M to move the CP within a line, 
but you need not do so. For example, if you move the 
CP past a carriage return character, it will move into 
another line of text. 

If the current line (displayed by TSS) is: 

{]) REALIST, ITD, LB 

And you type the command 2MSTSS 

!2MSTSS 
RE(\)ALINT,ITD,LB 



Then, type -2M STSS to restore the CP to its original 

position: 

I-2MSTSS 

(]} REAL INT ITD, LB 



Delete Lines (K) 

Sometimes you may want to delete an entire line. 
(Often it's easier to delete a bad line and insert a new 
one than to try to correct the original.) To delete one or 
more lines, use the K command. This command takes 
an argument n indicating how many tines to delete: 

3KSS 

This command kills (deletes) three lines from the 
current CP position (the first line is everything to the 
right of the CP on the current line). We suggest that 
you use only positive values of n to keep your editing 
simple. (A negative n when the CP is in the middle of a 
line will delete not only the previous line but also the 
left portion of the current line). 

For example, assume you want to delete the second 
line, which begins with 5. First, use the S, L, and T 
commands to check the surrounding lines: 

USS5S-1LS3TSS 

REAL INT. ITD, LB 

5 TYPE 'ENTER AMOUNT, RATE, YEARS'' 

TYPE 'AND, FOR SUMMAR YOR I FOR " 



Then get to the target line with S, and verify the line 
with T. Get to the beginning of the line with L, delete 
the line with K, and verify the deletion with T. 

!S5$T$S 

5(f) TYPE ' 'ENTER A MO UN T, RA TE, YEARS ' ' 

SLS1KS-1LS2TSS 

REALIST. ITD, LB 

TYPE "AND, FOR SUMMAR Y AND I FOR " 



To restore the line, set CP position after the carriage 
return character in line one, and use the I command: 

IJSSLB) 

ss 

SIStabTYPE "ENTER AMOUNT.RATE, YEARS") 
SS 
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Terminate Editing (UE or US) 

After you finish editing, you must key in the UE 
command. This applies ail the editing changes you 
made to this Hie, and it completes the creation of the 
new, updated file. To save the original file as a backup 
file, key in US instead of UE. Superedit will then 
update the file and save the original file under 
filename. BU, deleting any older filename. BU first. You 
can then issue the H command to return to the CLI. 



the edit buffer will be lost. Therefore, avoid starting a 
command string with H accidentally. For instance, you 
might forget to begin this string with I, S, or C: 

!HELP RETRIEVE MY EDIT BUFFERSS 

and Superedit would terminate, returning vou to the 
CLI: 



Return to the CLI (H) 

The H command returns you to the CLI. You will 
usually issue this command after UE or US, but you 
may issue H at any time. You might key in H without 
UE if you realized that you have made some substantial 
editing errors, and that it would be easier to start all 
over again than to try to correct the errors by working 
on the updated file. H without UE returns you to the 
CLI immediately, without writing out the edit buffer or 
copying the remainder of the input file. It leaves your 
original file intact on disk. 

/Iwcommand string starting with an H will terminate 
Superedit and return to the CLI, and all work done in 



Before turning to the remaining chapters, you should 
sit down at a terminal and practice with Superedit. Try- 
to create and make some minor modifications to files 
using Superedit. When you become familiar with 
Superedit, you can then proceed to learn how to write a 
program under RDOS or DOS. Via the CLI, you may 
want to create directories for your Superedit files, 
LIST, MOVE, or DUMP them. 



Summary of Editing Commands 

Table 5-1 summarizes each of the commands we've 
discussed and gives some simple examples of their use. 
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Table 5-1. Superedit Command Examples 



Command 



#T 



Examples 



#TSS 



3TSS 



TSS 



SOUNT. STSS 



JS5T 



LSI) 

) 
SS 

3LSS 



Result 



Type the entire buffer 
on the console. 

Type three lines from 
CP including the 
current line. 

Type the current line 
and show where the 
character pointer is. 

Given this string. 

...ENTER AMOUNT, 
RATE AS... 

this command shows 
the pointer located 
immediately after the 
comma after 
AMOUNT: 

...ENTER AMOUNTED 
PATE AS... 

Go to the start of the 
buffer and type the 
first 5 lines. 

Insert two blank lines 
before the current 
line. 

Set the CP to the start 
of the 3rd line down 
from the current line. 



Command 



Examples 



ZMSTS-2MSTSS 



SOUNT.SS 



SOUNT.SS 
CTERSTESS 



L$ I HELLOSS 



LS1KSS 



UE 
US 



UEHSS 
USHSS 



Result 



Move the CP two 
characters right, type 
line, then move the 
CP two characters left, 
type line. 

Set the CP after the 
comma following 
OUST as shown in 
this example string: 

...ENTER AMOUNT,... 

Set the CP after 
OUNT, then change 
TER toTE Applied to 
this string, 

...ENTER AMOUNT, 
RATER AS... 

it produces this result: 

...ENTER AMOUNT, 
RATE AS... 

Insert the string 
HELLO before the 
current line. 

Delete the entire 
current line. 

Apply editing changes 
to the file, close it, 
and return to the CLl. 



End of Chapter 
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Chapter 6 
Instant FORTRAN IV Programming 



This chapter assumes thai you have the optional 
FORTRAN IV compiler utility programs, and that you 
have loaded them, along with the FORTRAN libraries, 
into your master directory, as described in an appendix 
of the FORTRAN IV User's Manual.The FORTRAN 
IV compiler consists of two files: FORT.SV and 
FIV.SV. (If your machine has only 16K of memory, do 
not use the FIV.SV file; instead use FIVNS8.SV, " 
DUMP or COPY FIV.SV to save it, then delete the 
original and RENAME FIVNS8.SV to FIV.SV.) The 
compiler also expectsJhat the Extended Assembler, 
ASM.SV, is in this directory. 



5) Run the save file with the CLI command 
filename) 

6) If the program is correct, go to 9; if not, go to 7. 

7} Diagnose your program using runtime error 
messages or erroneous output. 

8) Goto 1. 



Program Steps 

These are the steps you follow to write a FORTRAN IV 
program. 

1) Create or edit a FORTRAN IV source file with 
Superedit. 

2) Compile and assemble the source file with the CLI 
command 

FORT filename) 

This produces a relocatable binary file. 

3) If there are any compiie-time errors, go to 1; if not, 
go to 4. 

4) Make the relocatable binary file into an executable 
save file with RLDR: 

RLDR filename [subroutine names...] FORTO. LB f ) 
FORT1 .LB FORT2.LB FORT3.LB SMPYD.LB} 



9) You're done! 



This chapter guides you through all the steps you need 
to write and execute such a program. 



Writing the FORTRAN Source Program 

The FORTRAN example in this chapter is a simple 
program to calculate home mortgage payments; it 
produces a schedule of monthly principal and interest. 
The program uses only ordinary arithmetic operations, 
calls no subroutines, and (excluding comments) is only 
about half a page long. The program uses two formulas. 
You need not understand how these formulas work to 
understand the illustration. We have chosen 
FORTRAN IV for this program (instead of FORTRAN 
5) because FORTRAN IV runs under both RDOS and 
DOS. 
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Figure 6-1 shows a flowchart for this program, and 
Figure 6-2 shows our initial version of the program, 
MORTGAGE.FR, complete with errors. (We used 
portions of this program for editing examples in the fast 
chapter.) 



We assume that you'll be writing, compiling, and 
loading this program in the master directory. Later, you 
might want to create a directory (e.g., F0RT4) to hold 
your FORTRAN IV programs. In this directory, you'd 
need links to the Superedit files ASM.SV, RLDR.SV, 
RLDR.OL, SYS.LB, and the FORTRAN libraries 
(FORTn.LB). 



Program MORTGAGE.FR reads input from the 
console (ACCEPT statement), and writes its results to 
the console (device number 10). If your system has a 
line printer, you can direct output to the printer by 
substituting the printer device number (12) for console 
output number (10) in each WRITE statement after 
line 1 10 (except for statement 40). For example, the 
line following the format statement in line 1 10 would 
become 



WRITE (12,120) PAY. 

You should examine Figure 6-2 before proceeding to 
the next section. 



Compiling the FORTRAN Program 

Having written an initial version of MORTGAGE.FR, 
we now compile it. The FORTRAN IV compiler 
produces an intermediate assembly-language program, 
then invokes the Extended Assembler, which produces 
a binary program. 

Since the initial version probably has some syntactical 
errors in it, we use the global /N switch, which tells the 

compiler to scan the input for errors, but produces no 
output file (producing one would do no harm, but it 
would take longer). After making sure that the current 
directory has the compiler tiles and the Extended 
Assembler (or links to these), type: 



t >■ 



)£!:. •/ 



;~2»>;;»'. .-"-v. 






'K2^ii 



bw^m 




SO-00741 



FORT/N MORTGAGE) 



Figure 6- /. MOR TGA GE. FR Program Flo wchart 
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REAL INT, ITD, LB ; £l Se these would be fntegefJ. 

5 type "enter amount, rate, years" 

type "and, for summary or 1 for" 

TYPE "FULL SCHEDULE. SEPARATE EACH- 
TYPE "ENTRY WITH A COMMA." 
TYPE -TERMINATE INPUT WITH RETURN, " 
ACCEPT A*OUNT»RATE,IYEARS»IFULL ; Get figures from console. 

C Change yearly rate RATE to monthly rate S, 

R s RATE/12 
C Change years lYEARS to months N. 

N s ]YEARS»12 

C Calculate monthly payment PAY, write heacer anc PAY. 

PAY s AMOUNT*R*UtR)**N/CCHR)**N-i) 

*RITE (10,110) AMOUNT, PATE, IYEARS 
110 FORVA7 C1H0, -AMOUNT s S»,F9.2,/," INTEREST RATE s",F7.«,/, 

x ;Rm N ( r"h""p"'" YEARS "' / ' ; Ch,r - ,n P0! - 6 c ° nt " ,nu " ""• 

120 FORMAT (1H0, "MONTHLY PAYMENT = $%P10.2,/} 

C Summary or full scheaule? 

IF (IFULl ,LE. 0) GO TO 40 

C Full schedule -- set up variables. 

LS = AMOUNT ; Initial Loan Balance equals original amount. 
NN s H ' Save original number of months in NN. 

ITD s ; Interest To Date is initially 0. 

C Write header, then calculate anc *rite figures month by m nth. 

WRITE (10,130} 
130 FORMAT UH0," NUM",7X, "INTEREST", 5X,"PRlN. PAY PRIN " 
X "BAL",6X, "INTEREST PAID TO DATE",/) 

DO 30 1=1, NN ; DO until you re a c h NN months — 
C Calculate amount of principal "in payment, PN. 

PN s LB*R/( (Rti)**N-n 
C Decrement month. 

N = N-l 
C Calculate amount of interest "in payment, INT. 

INT s PAY-PN 
C Upaate loan balance. 

LB s LB-PN 
C Update "interest paid to date. 

ITD = ITD+INT 
C Write figures for this month. 

WRITE (10,140) J, INT, PN, LB, ITD 

« r^!JI,J 1H0 ' I3 ' 7X '" $ "' F9 - 2 '" S%".^" S«,F9.2, 8X,-S-, F0.2) 
jo CONTINut 



ao 



ACCEPT H TYPE 1 TO REPEAT, TO STOP, », ISTOP 
IF (ISTOP ,6T. 0) uO TO 5 

END 



Figure 6-2. MOR TGA GE.FR Program With Errors 
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During the compilation, five errors appear on the 
screen along with the source lines where these errors 
may have occurred; 



The first error message claims that the error occurs at 
approximately the 13th character (CHR) position in the 
line. 





REAL INT, ITD, 


LB 






1 t * * 


060 •** CHR 10 
INT s PAY-PN 








I « * * 


003 *** CHR 05 










WRITE (10,1*12) 


It 


INT, PN, LB, 


ITD 


; * * * 


0«7 *** CHR 01 










WRITE (10,140) 


I, 


INT, PN, LB, 


ITD 


j * * * 


060 *** CHR 23 








» 


IF tISTOP .GT, 


0) 


GO TO 5 




,• *** 


111 *** CHR 01 








PROGRAM IS RELOCATABLE 












.TITL .N-AIN 





Figure 6-3. Compile- Time Error Messages 

The iast line isn't an error; it results from the 
assembler's scan of the program. 

Note we said may have occurred. Actually the offending 
line of source code may be located one or two lines 
before the one displayed with an error code. Looking in 
Appendix B of the FOR TRAS I 1 ' User's Manual, you'll 
find two sets of numeric error codes. The first set, 
entitled FORTRAS IV ERROR MESSAGES, are those 
codes which apply to compile-time errors; the second 
set, FORTRAS IV RUS-TIME ERROR MESSAGES, 
describes errors you can receive when you execute 
your program. 

The codes shown in Figure 6-3 have the following 
meanings: 

060 Error in formal syntactical structure; identifier is 

of wrong variety. 

003 Unknown statement type. 

047 Illegal operand types for current operator. 

1 1 1 Hollerith constant not ended at statement end. 

You shall see that most of these errors result from a 
single error and, in general, that these error codes do 
little more than point us in the right direction. 



REAL INT, ITD, LB 



(Character positions are counted from the left margin, 
position 1 .) The statement's syntax seems ok; but the 
name of one of our variables, INT, is the same as that 
of a predefined FORTRAN library function-INT for 
integer. This caused the problem, and changing the 
name of this variable to INTEREST clears it up. 
Because this error caused the compiler to reject the 
line, you might expect some other lines using the same 
variables (INT, ITD, and LB) to also be flagged as bad. 
You would be right; all of the remaining errors except 
the iast result from this first error. 



The last error is kind of perplexing because the IF 
statement syntax is perfect. The error actually occurred 
on the preceding line, statement 40, where we began the 
Hollerith string with a quote (") and ended it with an 
apostrophe O. This often happens in FORTRAN: the 
compiler flags an innocent line when the preceding line 
is bad. It occurs because the compiler has already 
processed the innocent line when it detects the error. 



Using Superedit, correct the errors with selective S and 
C commands; e.g., CINTSINTERESTSTSS. The five 
erroneous lines should look like this after you change 
them: 



REAL INTEREST, ITD, LB 

INTEREST = PAY-PN 

ITD = ITD -f INTEREST 

WRITE (1 0,1 40) NP, INTEREST, PN, LB, ITD 

40 ACCEPT "TYPE 1 TO REPEAT, TO STOP.", ISTOP 



After these changes, repeat the FORT command, this 
time omitting the /N global switch. The compilation 
and assembly should proceed without error messages. 
When assembly is completed, you'll receive the R 
prompt, indicating that you can now begin the next step 
in your procedure: processing with the relocatable 
loader uliliu. RLDR. 
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Creating the Save Fife 

The RLDR command line for MORTGAGE is: 

RLDR MORTGAGE FORTO.LB FORTLLBt) 
FORT2.LB FORT3.LB SMPYD.LB) 

The -.LB names following MORTGAGE are the names 

of libraries that you must always use when loading a 
FORTRAN IV program. Typing the four library names 
is a nuisance; eventually you may want to merge the 
libraries under a single name (e.g., FORT. LB) with the 
Library File Editor (LFE) utility. 

Later, for more on the LFE command, see the 
appropriate appendix of the FORTR AS IV User's 
Manual. Note that if your computer has hardware 
muitipiy-divide. you might want to select the 
hardware-muitiply-divide library (instead of 
SMPYD.LB) for later programs, or for your single 
merged library file. For now, if you want, you can 
create a CLI macro to do the load: or you can simply 
type in the filenames. 

As RLDR processes MORTGAGE, you see the 

following series of messages on the console: 

MOR TGA GE.SVL OA DED BY RLDR 

R E I xx.xx A T lime date 

.MAIS 

I 

FREAD 



SMAX 012177 

ZMAX 0002 JO 

CSZE 000000 

EST 000000 

SST 000000 

Following the initial line, which tells you the name of 
the save file and when it was created, RLDR describes 
all the modules that it extracted from the FORTRAN 
libraries and the system library to build the program. 
.MAIN is always the title of the main FORTRAN 
program; you can ignore the other modules. The next 
group of entries describes the memory addresses at 
which MORTGAGE will execute. NM AX is the 
highest address of normal-relocatable code plus one. 

CSZE is the unlabeled common area size; here, there is 
none, EST and SST are the end and start of the symbol 
table, and, again, there is none. In most FORTRAN 
applications, you won't care about the information 
produced by RLDR; but if you plan to run dual 
programs or have limited memory, the NMAX and 
ZMAX figures may concern you. You can find more 
detail on this in your system reference manual or the 
Extended Relocatable Loaders User s Manual. 



Executing the FORTRAN Program 

You now proceed to the next step, executing 
MORTGAGE.SV. To execute this or any other 
program, simply type the program name and follow it 
with a ). 

MORTGAGE) 

ESTER AMOUST. RATE. YEARS 

ASD, FOR SUMMAR Y OR I FOR 

FULL SCHEDULE. SEPARA TE EACH 

ESTRY WITH A COMMA. 

TERM I SATE IS PUT WITH RETURS. 

You then respond with a request for the summary 
information (monthlv pavment onlv) uiven a mortaaae 
of $20,000 at 9% for 25 years: 

2000O,.O9,25,O) 

MORTGAGE then types: 

AMOUST = S20000. 00 
ISTERESTRATE = 0.0900 
LOAS LIFE IS 25 YEARS 

MOSTHL YPA YMEST = S167.S4 

on the console, and then says: 

TYPE I TO REPEA T, TO STOP 

To continue, type: 

1) 

Since you responded with 1 , the same instructions 
appear on the console. This time, enter the same 
arguments but ask for a full schedule: 

20000,. 09, 25,1) 

AMOUST = S20000. 00 
IS TER EST RATE = 0. 0900 
L OA S L IFE IS 25 YEA R S 

MOSTHL YPA YMEST = SI 67 84 
SUM. INTEREST PR/N. PA Y... 

FA TAL R USTIME ERROR 15 A TLOC. xxxxxx 

CA LLEDFR OM LOG. yyvvvv 

R 

and find the CLI running on the console. The 
FORTRAN IV manual describes Runtime Error 75as a 

"field" error, which might have occurred in an F or E 
entry in a FORMAT statement. Checking the Fs in our 
program, we find a typo in statement 140: F0. 2 should 
be F9.2. Fix this with the Superedit command 

JSCF0.2SF9.2STSS 
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Recompile the program, and run it through RLDR 
again. Then execute MORTGAGE, and enter the 
figures: 

20000, .09,25,1 ) 

and the long listing begins. If the console is a display 
terminal, you can use CTRL-S. CTRL-Q to stop and 
start display. If you wrote the program for the line 
printer, the listing starts on the printer. The beginning 
of* this summary appears in Figure 6-4; the interest total 
at the end of the whole summary is pretty appalling. 

To terminate MORTGAGE and return to the CLI. 
type to the REPEAT query. CTRL-A would do this at 
any time, but it wouldn't be as neat. 



Compile, Load and Go 

Instead of compiling a FORTRAN IV source program 
(FORT command), loading it (RLDR command"), and 
executing it (programname command), you can use 
the CLG command to combine these steps. CLG is a 
program that directs the compiler, then the loader; 
then it executes the resultant save file. Before you can 
use CLG, you must merge the FORTRAN libraries 
into a single library named FORT. LB with the Library 
File Editor Merge command; this is described in an 
appendix of the FORTRAN IV User's Manual. Also, the 
source file, CLG.SV, and all other utilities involved 
must be in the current directory (or linked to it). 



AMOUNT s S 28800.00 
INTEREST RATE = 0.0900 
LCAN LIFE IS 25 YEARS 

MONTHLY PAYMENT = S 



MJM 

1 

2 
5 

a 

5 

6 
7 

8 

9 
10 
II 

12 
13 

14 



16?. 8a 



INTEREST PRIN. PAY 


PRIN.8AL 


S 150.00 


I 17.84 


S 19982.16 


$ 149.87 


S 17.98 


I 19964.18 


S 149.73 


I 18.11 


5 19946.07 


$ 149.60 


5 18.25 


S 19927.83 


$ 149.46 


S 18.38 


S 19909,44 


S 149.32 J 


I 18.52 


B 19890.93 


S 149.18 J 


I 18.66 2 


5 19872.27 


S 149,04 J 


I 18.80 i 


I 19853.46 


3 148.90 3 


5 18.94 3 


5 19834.52 


S 148.76 3 


i 19.08 3 


5 19815,44 


$ 148.62 J 


» 19.23 3 


» 19796. 2J 


$ 148.47 3 


19.37 3 


> 19776.84 


S 143,33 3 


19.51 3 


» 19757.33 


$ 148.18 i 


19.66 3 


19737.67 



INTEREST PAID TO DATE 

150.02 

299.87 

449.62 

599.19 

748.65 

897.97 
1047.15 
1 196.20 
1345.10 
1493.86 
1642.47 
1790.94 
1939.2? 
2087.45 



Figure 6-4. Sample of Extended Schedule from MQR TGA GE 



End of Chapter 
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Chapter 7 
Extended BASIC Programming 



This chapter leads you through a sample session in 
Extended BASIC. It assumes that you have some 
experience with the BASIC language, and that you 
have loaded the BASIC System Generation program 
(BSG) from tape or diskette, and generated a BASIC 
system. Chapter 2, the Extended BASIC System 
Manager's Guide covers BSG. This chapter also assumes 
that you are the only person on the system using 
BASIC. On a multiuser BASIC system, log on 
according to your system manager. Skip step 1 below 
and all the CLI material in this chapter. 

Aside from the Extended BASIC System Manager's 
Guide, we offer two other books on Extended BASIC: 
basic BASIC, for beginners, and the Extended BASIC 
User's Manual, which covers the features and 
commands of our BASIC. Here are the steps you follow 
to create a BASIC program: 



1) Invoke the BASIC interpreter and get into BASIC 

by typing the CLI command: 

BASIC) 



2) Write a series of BASIC program statements. 
BASIC has its own editor and an interactive 
compiler that rejects bad syntax as you type each 
statement. 



3) Run the program with the BASIC command: 
RUN} 



4) If the program runs correctly, you're done! Save 
the program on disk with the LIST command. Type 
BYEJtoget back to the CLI. 

5) If your program contains runtime errors, fix it 
using erroneous output or BASIC runtime error 
messages. Go to 3. 

Writing BASIC Programs 

You write a BASIC program as a series of statements, 
which you must begin with a number between 1 and 
9999. Each statement includes a command to BASIC, 
which then executes the statements sequentially, by 
number; thus, your program can do useful work. 

At various points, you can examine the statements in 
your program with the LIST command, or tell BASIC 
to execute the statements with the RUN command. 
BASIC'S error messages will help you correct errors; 
you can correct offending statements by typing their 
line numbers, then the new text. When you're satisfied 
with a program, save it on disk with the command LIST 
"filename"}; later, you can read it back into memory 
with the command ENTER "filename"). To print it on 
the line printer, type LIST "SLPT"). To start work on 
another program, type NEW), then proceed. To sign off 
BASIC and return to the CLI, type BYE). 

You can execute a BASIC program only from BASIC; 
you can't do it from the CLI. The BASIC interpreter 
accepts both upper- and lowercase characters, and 
translates lowercase letters to uppercase. You can make 
lowercase text part of your program (in PRINT and 
comment statements) by editing your BASIC program 
file with Superedit, after the program runs. 
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Sampfe Session 

This is a simple session with Extended BASIC. Bring up 
RDOS or DOS (if it isn't already running), sit down at 
the console, and try it. First, DIR to the partition or 
diskette that contains the BASIC directory 
(BASIC. DR). BASIC requires this directory to run, 
although you cannot invoke BASIC from inside it. ' 



DIR proper-directory) 
R 



The person who generated the BASIC system could 
have named it anything he or she wanted. We're 
assuming that its name is BASIC, filename BASIC.SV. 

BASIC) 

EXTENDED BASIC R E \ ISIONxx.xx date 

OPER 

(Depending on your BASIC, it may request a password 
or device specifier information here. For password 
details, see the BASIC User's Manual. If it asks 
DIRECTORY SPECIFIER?, answer 

BASIC) 

Now, all BASIC programs you LIST to disk will go into 
directory BASIC. DR. 

If BASIC. DR doesn't exist, you'll find yourself back in 
the CLI. Proceed to create it (CDiR BASIC)), and tvpe 
BASIC) again. 

When BASIC comes up, it issues an asterisk (*) 
prompt. When this prompt appears, you can issue 
BASIC commands and statements. 

"PRINT HELLO) 
ERROR 02-SYSTAX 

PRINT "HELLO") 
HELLO 



You must include string literals in quotes. For an 
explanation of other BASIC error messages, see 
Appendix A of the Extended BASIC User's Manual. 

*10 REM THIS IS A REMARKS LINE ) 

*20READA,B,C,D) 

'30PR1NTD-A + B*C T D) 

*40 DATA 2,3,4,5) 

•LIST) 

0010 REM THIS IS A REMARKS LINE. 

0020 READ A, B, C,D 

0030 PRINT D-A+B*C\D 

0040 DATA 2,3,4,5 

*RUN) 

3075 

END A TO:. '40 



BASIC^evaluated the expression as [5-2 + (C D *B)J = 3 
+ (4 s *3) = 3075. The exponential character is an 
uparrow (f ) produced by SHIFT-6 or SHIFT-N. 

Now, to store the little program on disk: 
*LIST"ARITH1") 

You can use any RDOS/DOS filename, with an 
extension if you want, for a BASIC program. Later, you 
can read this program back into memory by this 
filename: 

•ENTER "AR1TH1") 

When you want to sign off BASIC, type: 

•BYE) 

(log off and accounting information) 

R 

Now get back into BASIC for the sample session: 

BASIC) 
EXTENDED... 
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Strings and Arrays 

BASIC strings and arrays allow you to store and access 
alphanumeric strings and numbers by subscript. You 
can declare a string or array, assign it a fixed number of 

elements with a DIM statement, and then access 
elements by the string or array name, followed by the 
element subscript number in parentheses or brackets. 
String names begin with a letter and end with a dollar 
sign (e.g., AS, A IS); array names don't include the 
dollar sign (e.g., A,A1). For example, type: 

•NEW) 

*10 DIM NS(30)) 

*20 INPUT "WHAT'S YOUR NAME?",N$) 

Run it: 

•RUN) 

WHAT'S YOUR SAME? 

Type a name: 

WliA T'S YOUR SAME? MELINA) 

Line 20 uses a siring literal, which you simply enclose in 
quotes, and BASIC accepts it literally; line 10 
dimensions string variable, NS. Your response assigned 
values MELINA to the first six elements of NS, which 
look like this in memory: 

M ELINA null.... null 
NS(1) NS(2) NS<3) NS(4) NS(5) NS(6) N${7) NS(30) 

Elements SN(7) through SN(30) contain nulls (ASCII 
000). 

You can reference substrings using the form 
stnngname(elementl, elementn). For example, append a 
statement to your program and run it: 

•30PRINTN$(1,3)) 

•RUN) 

WHA T'S YOUR SAME? MELINA) 
MEL 



The subscripts specified elements 1 through 3- hence 
MEL. 

Now, we can try a more sophisticated version of the 
program, which dimensions two strings, compares 
them, and acts on the comparison. Note that whenever 
you change mode in a PRINT statement, from string 
literal or string variable or numeric variable, you must 
insert a semicolon (or comma). This rule accounts for 
the complex punctuation in lines 30 and 80. Type 
NEW), then type in this program. If you make'a 
mistake, retype the bad line from the beginning. 



10 DIM NS(30)OS(30)) 

20 INPUT "WHAT'S YOUR NAME?Z",NS) 

30 PRINT "IS IT REALLYZ";NS;"?C:TYPE IT AGAIN ") 

40 INPUT OS) 

50 IF OSONS THEN GOTO 80) 

60 PRINT NS;"GMUST REALLY BE YOUR NAME ") 

70 STOP) 

80 PRINT'iS ITZ";NS;"CORZ;";OS;"?" 

Now, try running the program. If you want to save it on 
disk, type LIST "name"), where name is any legal RDOS 
or DOS filename. Chapter 8 of baste BASIC describes 
strings further. 

BASIC arrays resemble strings, but each element in an 
array must be a number, whereas each element in a 
string must be an alphanumeric character. For example, 

10 DIM A{20)) 
20AO) =9.5) 
30A(2) - 46) 
40A(20) = A(1)+A(2)) 
50 PRINT A(1).A(2),A(20)) 

These statements dimension array A and assign values 
to three of its elements; the other elements contain nulls. 
Chapter 7 of basic BASIC explains elementary arrays. 

BASIC Program 

The BASIC program flowcharted in Figure 7-1 and 
shown in Figure 7-2 is a variation of the FORTRAN 

program in Chapter 6. It computes mortgage payments, 
taxes, and deductions in a general way; and writes its 
computations to the console. You can enter the 
program using Superedit from the BASIC directory 
(link to the Superedit files first), or you can use the 
BASIC interpreter. If you use the BASIC interpreter, it 
will check the syntax of each line as you type it in. If 
you use Superedit and make a syntax mistake, the 
BASIC interpreter will reject the bad line when you 
ENTER the program. 

If you use the BASIC interpreter, you can examine the 
lines you've typed by typing LIST. To list a portion of 

the lines, type LIST number comma number, where each 
number is a line number, e.g., LIST 10,100). 

Periodically as you type the program in, and when 
you're done, type LIST "MORTGAGE. BA", to write the 
program to disk; you can also get a hardcopy listing by 
typing LIST), or LIST "$LPT") if you have a line printer. 

If you want the program to write to the line printer, 
insert the statement OPEN FILE (0,2), "SLPT" before 
the first PRINT statement. Then change the PRINT or 
PRINT USING statements to PRINT FILE (0), or PRINT 
FILE (0), USING statements wherever you want the 
program to write to the printer. Insert the statement 
CLOSE right before the STOP statement (line 300). 

You should examine Figures 7-1 and 7-2 before 
proceeding to the next section. 
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0010 REM PROGRAM MORTGAGE. BA, COMPUTES MORTGAGE PAYMENTS, HAS TAX SUBROUTINE, 

0020 PRINT »<12> I CALCULATE MORTGAGE PAYMENTS, INTEREST* AND TAXES." 

0033 PRINT "TYPE AMOUNT OF PRINCIPAL* INTEREST RATE IN WHOLE NUMBERS," 

00a0 PRINT "MORTGAGE LIFE IN YEARS, AND ANNUAL PROPERTY TAX BILL FOR HOUSE." 

0050 PRINT "SEPARATE ENTRIES WITH A COMMA,' FOR EXAMPLE 40000, 1 0. 5 , 25, 2000 . » 

0060 PRINT 

0070 PRINT » AMOUNT? RATE? YEARS? TAXES?" 

0080 INPUT " ? ",A,R1,Y,T 

02*00 LET R = RlJl283 THLY "*" R CR1/l23 ' MAKE INT0 FRA CTI0N AS Rl WAS WHOLE NUMBER. 

0110 REM GET NUMBER OF MONTHS M FOR LOAN. 

0120 LET M*l2ty 

0130 REM COMPUTE MONTHLY PAYMENT. 

0140 LET P*A*R*(ItR)TM/((UR)TM«l) 

0150 REM DEFINE FORMAT FS THAT ROUNDS NUMBERS TO NEAREST WHOLE CENT. 
0160 LET FSx-------- , Mst H 

0180 REM PRINT TOTALS AND GIVE OPTION FOR TAX SUBROUTINE. 

0190 PRINT "MONTHLY PAYMENT: TAXES: HIDEOUS TOTAL!" 

0200 PRINT USING FS,P," »,T," %P + T 

0210 PRINT 

llll lll H1 " WANT T ° C0MPUTE THE TRUE COST AFTER U.S. TAX DEDUCTIONS ON THE" 
0230 PRINT "INTEREST AND TAXES? YOU MUST ITEMIZE TO QUALIFY." 
Q2(i2 INPUT "ANSWER Y (YES) OR N (NO). «,Q$ 

siis ini.:" p ?H« c «?j iii uh prosmm again ' anything else t ° stop - ■•« 

0300 STOP 

1000 REM TAX DEDUCTION COMPUTATION SUBROUTINE 

1010 INPUT "WHAT IS YOUR TAX BRACKET, IN WHOLE NUMBERS? »,B1 

1020 LET BsBl/100 

1030 PRINT 

\lil P rll„l ."ST l LIST PAYMENTS f= 0R THE FIRST TWO YEARS? I HAVE" 

\lll oci U Ll W / lGURE ™ E INTEREST ANYWAY. ANSWER Y CYESJ OR N (NO). %QS 

1070 LET Ai = A VARIABLES Al { pR ^CIPAL PD PER MONTH) AND II (FOR TOTAL INTEREST),* 

1080 LET Hs0 

1090 IF GS<>"Y" THEN GOTO 1110 

1100 PRINT " MONTH PRIN. INT. INT. TOTAL" 

1120 FOR J»r°TO N |5 T L0 ° P C ° MPUTES £ ° p TlONALLY LISTS) FIGURES BY MONTH AND TOTALS. 

1130 LET PlsAl*R/( (Rti)tM-l) 

1140 LET Ii = I 1 + CP-P1 3 

1150 LET AisAl-Pi 

1160 IF Q$o"y" THEN GOTO 1180 

1170 PRINT USING FS,J,P1,P-P1,I1 

1180 NEXT J 

1190 PRINT 

lflS 111 DxTtIl52 CTIONS ° F ° R 1 ¥£AR ' TCAXES) * lU2 £HALF ° F 2 YRS ' INTEREST J 
1220 PRINT "ANNUAL MORTGAGE-RELATED DEDUCTIONS ARE:" 

1230 PRINT USING FS,D 

Mil pa!!I !!!, U I ! MUST SUBTRACT THE "200 STANDARD (0 BRACKET) DEDUCTION- 

All lli lill.l 2 W HJ0 THE m TA8LE3, THE TRUE M0NTHLY C0ST ISI * 

llll let c G "p^1 2 ). ; B "f/ T ;2r oTAL ¥Q * PAY s p+m) ' ((BRKT * A0J - DE0S)/12) 

1290 PRINT USING F$,C 

Jiff dd INT " ****SUMMARY****« 

!i EL" ing l ^'^^y^uc RAn ' " shpayi ""■ T - E " sT =" 



Figure 7-2. MORTGAGE Program With Errors 
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Running the BASIC Program 

To run the program, get into BASIC (if you're not 

already there), and type: 

•NEW) 

ft 

ENTER "MORTGAGE. BA") (or whatever name and 

extension you gave it) 

•RUN) 

/ CALCULA TEMOR TGA GE PA YMENTS, 

INTEREST, AND TAXES. 

TYPE AMOUNT OF PRINCIPAL, INTEREST RA TE 

IN WHOLE NUMBERS, 

MORTAGE LIFE IN YEARS, AND ANNUAL 

PROPER TY TAX BILL FOR HOUSE. 

SEPARATE ENTRIES WITH A COMMA; FOR 

EXAMPLE 40000, 10.5, 25, 2000. 

AMOUNT? RATE? YEARS? TAXES? 



Respond with some plausible figures: 

40000, 10.5, 25, 2000) 

and the program responds: 

MONTHLY PAYMENT; TAXES: HIDEOUS TOTAL: 

377,67 2000.00 2377.67 

H 'ANT TO COMPUTE THE TR UE COST 
...ITEMIZE TO QUALIFY. 
ANSWER Y (YES) OR N (NO). 

This seems a little high -- over S2, 000 per month. We 

forgot to convert the yearly tax figure to months. 
(Depending on the precision generated on your BASIC 
system, your answers may differ slightly.) ft would be 
meaningless to proceed so type: 

N) 

TYPE Y(YES) TO RUN PROGRAM AGAIW 
ANYTHING ELSE TO STOP ) 

STOP AT 300 



The problem is in line 200, and you can fix it by 
dividing the tax variable, T, by 12. Replace the existing 
line 200 by typing: 

200 PRINT USING FS,P,"Z=",T/t 2,"Z",P + T/1 2) 



and run it again: 

RUN) 

I CALCULATE... I 

AMOUNT? RATE? YEARS? TAXES? 

? 40000,1 0.5,25,2000) 

MONTHLY PAYMENT; TAXES: HIDEOUS TOTAL; 

577.67 J66.67 544.34 

WANT TO COMPUTE.. 
ANSWER Y (YES) OR N (NO). 

These figures are more reasonable so you can proceed 
with the program: 



Y) 



WHAT IS YOUR TAX BRACKET, IN WHOLE 
NUMBERS? 

The tax bracket issue is explained later in this chapter. 
For now, try 25, a typical bracket: 

25) 

SHO ULD I LIST PA YMENTS FOR 
...ANSWER Y (YES) OR N (NO). Y) 



MONTH 


PR IN. 


INT. 


INT. TOTAL 


1.00 


27.67 


350.00 


350.00 


2.00 


27.65 


350.02 


700.02 


3.00 


27.64 


350.04 


1050.06 


4.00 


27.62 


350.06 


1400.11 



MORTGAGE-RELATED DEDUCTIONS ARE- 

6202.63 

BUT 1 MUST SUBTRACT THES3200 
...TR UE MONTH L Y COST IS: 

481. 79 

****SUMMARY** % * 
LlFE:AMOUNT:RA TE:CASH PA Y:BRKT:TR UE 

COST; 

25. 00 40000. 00 1 0. 50 544. 34 2 S 00 48 1 79 

TYPE Y(YES) TO RUN PROGRAM AGAIN...'... 

It works? At least it appears to work. (Clearly, if the 
TRUE PAY figure exceeds the CASH PAY figure, it 
may not pay you to itemize.) Let's examine the interest 
schedule again, though-because the program bases its 
deductible figure on the last value of variable II in this 
schedule. 
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Unfortunately, there is a problem in this schedule-the 
amount of interest paid each month increases while it 
should decrease. This must be wrong, and being 
wrong, it voids the entire deduction figure. Looking 
over the FOR-NEXT loop that computes the monthly 
interest, note that we forgot to decrement the month 
indicator, N, for each circuit through the FOR-NEXT 
ioop. You can fix this easily. First, stop the program: 

) 

STOP AT 300 



You've fixed the program, so you can write it to disk 
under its original name; this overwrites the old, 
erroneous version: 

LIST "MORTGAGE. BA"} 



You can also print it (LIST "SLPT") if you have a line 
printer, or type it (LIST). To leave BASIC and return to 

the CLI, type: 

BYE) 



Having incremented line numbers by 10, you can easily 
insert a new statement: 

1155 LET M=M-1) 



Now RUN) it again, giving the same figures (40000, 
10.5, 25, 20, and 2000) and tax bracket (25), to 
compare the results. The monthly schedule now says: 



MONTH 


PR IN. 


1ST. 


INT. TOTAL 


LOO 


27.67 


350.00 


350.00 


2.00 


27.92 


349.76 


699.76 


3.00 


28.16 


349.51 


1049.27 


4.00 


28.41 


349.27 


1398.54 



MORTGAGE-RELATED DEDUCTIONS ARE- 
6164.34 

BUT 1 MUST SUBTRACT 
... TRUE MONTHLY COST IS: 

482.58 



****SUMMARY**** 
LIFE:AMOUNT;RA TE:CASH PA Y:BRKTTR UE 

COST: 

25.0040000.00 10.50 544.34 15 00 48? 58 

TYPE Y (YES) TO RUN PROGRAM AGAIN,!. 

Eureka! The interest is now declining, and the program 
works correctly. (The difference may not seem 
significant here, but if the FOR-NEXT loop covered 60 
months instead of 24; i.e., J = 1 TO 60; it would be 

immense.) 



All programs you write via the BASIC interpreter 
reside in the BASIC directory; the interpreter 
automatically goes to this directory when you invoke it. 

Itemized Deductions and Tax Bracket 

For simplicity, this sample BASIC program assumes 
you are married and, when you acquire this mortgage, 
you will start itemizing deductions instead of taking"the 
standard deduction. When you itemize, the IRS allows 
you to deduct only the itemized amount over the 
standard deduction (S3200 if married filing jointly, 
S2200 if single). The standard deduction is'aiready 
figured into the tax tables. This is why line 420 of'the 
program subtracts the standard deduction from the 
mortgage-related deductions. If you are, in fact, 
moving to itemized deductions, you can deduct much 
more than mortgage-related expenses (e.g., medical 
expenses, casualty losses), but the program doesn't 
deal with these. It figures the TRUE COST amount as 
if you were deducting oniyihe mortgage-related 
amounts. 

Thus, if the mortgage moves you from the standard 
deduction to itemized deductions, your real cost per 
month will be less than the TRUE COST figure. If this 
is true for you, you can modify the program to compute 
lhe I R . UE r, 8 ure more accurately. The critical figure is 
the * 4 3200" in line 1260. Your program statements 
should get all mortgage-unrelated deductions (medical, 
contributions, casualty losses, etc.) and put them in a 
variable, let's say Q. Then it should addQ to D in line 
1260; e.g., LET Dl = D + Q-3200. 

In any case, if you are single, change the 3200 in line 
1260 to 2200; e.g., LET Dl = D-2200. 
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Tax Bracket 

It's easy io find your tax bracket if you don't know it. 
Take the figure you used in the tax tables to find your 
tax, and subtract 3200 (if married filing jointly) or 2200 
(if single); this is your gross income less deductions. 

Multiply the number of exemptions you used to find 
your tax by 750, and subtract the pro'duct from the 
original figure. This is roughly your net income. 



Now look at the Tax Rate Schedules (not the Tax 
Tables) in any Form 1040 instruction book. In 
Schedule X or Y (single or married), find the two dollar 
figures that bracket your net income, and, moving one 
column to the right, find the figure followed by %. 



This, roughly, is your tax bracket because it indicates 
how much of the last taxable dollar went for taxes. 

For a tax-bracket example, assume that the figure you 
took to the tax tables was S23.000, and that you have 
three exemptions. 23,000 minus the standard (marital) 
deduction of 3, 200 is 19,800. 19,800 minus 3 x 750 is 
17,550. In Tax Rate Schedule Y, you find that 17,550 
falls between SI 5,200 and SI 9,200. Reading to the right 
on the same line, you find S3, 260 + 25%. Thus your tax 
bracket is 25% because the government took a quarter 
from the last taxable dollar. Thus you save a quarter for 
each dollar the new mortgage lets you deduct. (This 
procedure yields only an approximation -- because the 
mortgage deductions might drop you into a lower 
bracket, thus save you less in deductions - but it is a 
fairly close approximation.) 



End of Chapter 
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Chapter 8 
Assembly - Language Programming: 
The Assemblers 



This primer can't possibly teach you all you must know- 
to program in assembly language, but this chapter will 
introduce some of the basics. We assume that you have 
some familiarity with the mechanism of assembly 
language and with the instruction set for your 
computer. But even if you do not, you will profit by 
reading this chapter, for it will familiarize you with' 
fundamental concepts before you study them in greater 
detail. Also, you'll need some of the basics described in 
this chapter to fully understand the next chapter where 
we write, assemble, execute, and debug our own 
assembly language program. 

Before it can do useful work, a program must be 
translated into machine-level instructions. System 
software does this: programs like the FORTRAN 
compiler, the Relocatable Loader, and the BASIC 
interpreter, translate your program commands into 
machine code: binary numbers that physically direct the 
computer. Assembly language is no exception; it also 
employs symbolic commands which translate into 
machine code. The software that does the translation is 
called an assembler. 



The Assemblers 

You can choose between two assemblers: the 
iMacroassembler (MAC) and the Extended Assembler 
(ASM). MAC is more powerful and more flexible, 
while ASM is faster. Each assembler has a manual of its 
own, which you can read for more detail. For the 
concepts we'll study in this chapter, and the program 
we'll write in the next, there is no practical difference 
between the two. We have chosen to emphasize the 
Macroassembler (MAC); but if you want to use ASM, 
go ahead. The term assembler in this chapter and the 
next applies to either MAC or ASM. 



To produce a program, you start by coding a source file 
in assembly language and emerge with a save file. The 
sequence looks like this: 

SOURCEPROGRAM 

1 

MAC or ASM 

1 
SOURCEPROGRAM.RB 

! 

RLDR 

i 
SOURCEPROGRAM.SV 

A source program (also called a module) employs 
symbolic instruction codes (such as LDA 0,2 for "load 
the contents of location 2 into accumulator 0") and 
operating system calls (such as .RDL for "read a 
line"). Your modules will also use assembler 
pseudo-instructions (pseudo-ops), which direct the 
assembly process but do not result in any final program 
instructions themselves. 



Each is a two-pass assembler (i.e., it examines the 
modules twice), and at the end of the second pass, it 
produces one or more of the following: 



• an assembly listing of the module(s) 

• an error code listing 

• a binary module 



The assembly listing shows your original source 
moduie(s) and additional information such as the octal 
codes of your instructions and data, the absolute or 
relative locations of these items in the executable 
program, and other miscellaneous information. 
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Assembly errors are analagous to FORTRAN 
compile-time errors. They usually indicate syntactical 
errors, not errors of logic in your program. Unless vou 
send them to another file, error messages alwavs go to 
the console. The listing will also contain error codes 
beside each offending source line. 



After you have produced a binary module with no 
assembly errors, you then process it (perhaps alone 
wnh other modules) with RLDR (the Relocatable 
Loader) to produce an executable program. You then 
run the program, and if it does not work the way you 
want it to, you examine it with the debugger. 



The debugger lets you run any part of a program stop it 
temporarily so that you can examine the contents of 
memory locations or accumulators, and make 
temporary minor changes to the program. You will 
probably have to repeat the process of assembly 
processing with RLDR and execution/debugging 
several times before you produce a program that & works 
as you want it to. 



Understanding Program Listings 

Each line of source code that you write will have one or 
more of the following elements: 



• labels (names of locations) 

• instructions, system calls, or pseudo-ops 

• arguments (separated by spaces or commas) 

• comments (preceded by a semicolon) 



Tne assembler accepts free-form input, hence vou need 
not place any of these elements in anv specific line 
position. The only requirement for source code is that if 
tney appear m any line, the order of these elements 
must be label, instruction, arguments, and comments 
haen iaoel ends with a colon. For our purposes the 
assembler considers only ihe first five characters of 
each label to be significant (it cannot, for examole 
differentiate between the labels BEGIN' and 
BEGINNING). 



Each comment begins with a semicolon and extends to 
tne end of the line. The assemblers do not process 
comments; they merely pass them on intact to the 
program listing. Figure 8-1 shows vou a pace from an 
assembly listing. 



Nonce that there are three columns of numbers; to the 
right of these, you can see the source code that was 
input to the assembler. The source code starts in 
column 1 7 of the listing and extends to column 80 The 
enlarged view of the listing shows three source lines 
that use each of the source code elements- 



label 



AGAIN: 



instruction/ comments 
argument 



.SYSTM 

-GCHAR 
JMPER 



;THISIS 

;GET 



The label is at the left, the instructions next, argument 
(third line) next, and the comments are on the richt 
We aligned labels, instructions/areuments, and " 
comments to make the listing easier to read, but we 
need not have done so; the assembler requires only 
that you follow the sequence of label (if anv) 
instruction, arguments (if any), and comments (if anv) 
within a line. 

Figure 8-1 also shows you what the columns of 
numbers mean. Columns 1 and 2 contain the line 
numbers for information displayed on each pace The 
assembler starts a new listing page after the 60th line 
unless you inserted a form feed character before this 
line. At the top of each page you will see a four-dicit 
number This is the page number. The assemblers use 
page and nne numbers in the alphabetical 
cross-reference they produce with each program listing 
(snown in Figure 8-2). Now return to Fieure 8-1 If anv 
source line has one or more assembly errors, columns! 
to j will contain from 1-3 alphabetic error codes. 

The next row of numbers is in octal and extends from 
columns 4 through 8. This sequence shows where each 
line of code will reside in the final procram These 
numbers may indicate absolute values (e.g., memory 
address 01 7) or they may indicate only a relative " 
position (the 3rd location from the becinnine of this 
series). Columns 10 through I5shcm the (unrclocaied) 
octal assembled value that will reside in this location if 
mis value is know when the program is assembled If 
tne assembler doesn't know this value perhaps 
Decause it references another module, the listinc shows 
tne contents as 000000. 

The two remaining columns, 9 and 16, contain 
relocation flags. In essence, relocation applied to an 
adaress (column 9) indicates thai RLDR, not the 
assembler, will assign a final address for the location 
since only it can determine where to place the code 
Relocation applied to data indicates where data or"" 
arguments are found. The symbols "and" indicate th- 
types of repeatability. Relocation is described in creai-r 
aeiail in tne appropriate Assembler user's manual 
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I5:li:«2 07/26/77 




k*2 
k*3 
k»« 

05 
fe36 
07 
08 
09 
10 
11 
12 
13 
la 
15 
16 
17 
IS 
19 
20 
21 
22 
21 
2a 
25 



8301 EXAMP MACHO REV 06,*30 

.TJTL EXAMPLE 
.NREl 
0000,dl -TXTM I ,-PACk .TXT BYTES LEFT-TO RIGHT. 

.ENT START, £«,TASM# AGAIN ,*OEPlN£D HERE. 
.LXTN .TASK,.PRI,,TQVLO ;C£T MULTITASK HANDLERS. 



00«3«0'006<5l 7 START; 

0000i , 02|«352 

00002'0«30776 

00003'y50a27 

3030«*320aJ3 

00005' 12&ad0 

00006 , 00&0| 7 

00007 '01 4377 

000l0'000y23 

00011 *020«32 

0«J0!2'077777 

000i3'020a3l 

00'dla'02aa3i 

000 15' 07 7 77 7 

00916*000415 
00^17*006^17 AGAIN: 
00020' 00 7 a 00 
00021 '000412 



.SYSTM 




.GChN 




JMP START 


STA i, 


ChNUM 


LOA B, 


NTTO 


SUB I, 


1 


.SYSTM 




.OPEN 


77 


JMP fcR 




LOA 0, 


Pa 


.PR I 




LDA 0, 


IOPkl 


LDA I," 


FASM 


.TASK 




JMP EN 




.SYSTM 


; 


.GCMAR 


; 


JMP fcR 





♦SYSTEM, GET A FREE 

JCHANNEL NUMBER, PUT IN AC2. 

JON ERROR, TRY AGAIN. 

,*STORE CHANNEL NUMBER IN "CHNUM*. 

IPOINTER TO CONSOLE OUTPUT NAME. 

,-USE DEFAULT DISABLE MASK. 

7SYSTE.M, OPEN CONSOLE OUT- 

;put un channel number In AC2. 

#ON ERROR, GET CLl TO REPORT. 

,*GET NUMBER "«". 

KMANGt YOUR PRIORITY TO a. 

IGET NErt TASK'S 10 ANO PRIORITY. 

JSTART NE'ft TASK AT THIS AOuRESS. 

JCREATE NErt TASK, WHICH GAINS CONTROL 

IMMEDIATELY, SINCE ITS* PRIORITY IS 3, 

•GET CLI TO REPORT ERROR. 
THIS IS THE MAIN KEYBOARD LISTENER TASK. 
GET A ChARACTEk FRUM THE CONSOLE. 



23 0001 7 '006017 AGAIN: 
23 00-220 'HO 7403 
25 00021 ' 000412 

1 2 4 5 6 7 8 9 10 11 12 13 14 15 16 17 



.SYSTM 
. G C h A R 

JMP ER 



/•THIS IS THE 
;GET A CHARA 



Line 

Number 
1 2 3 



Error Flag 

Location Counter (LO 



Data field Relocation Flag 
Data Field or E*pression 
Relocation Flag 



Comment 



Figure 8-1. Program Listing 
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Relocation flag 
Location 

Symbol [ 



T 

AGAIN 

B 

C 

CHNUM 

ER 

IDPRI 

NTTO 

pa 

P5 

START 

TASK1 

TGCLI 

.PRI 

.TASK 

.TOVL 



T 

008817' 
000851 ' 
000052' 
000032' 
000053' 
0200a« » 
08003?' 
00004 3' 
000053' 
000000' 
000045' 
000035* 
000031 ' 
000015' 
077777 



Svmbof Type 
i 

Page Line 

l/3i 



T 

EN 



£N 



EN 
£N 

XN 
XN 

XN 



14 

1/26 
1/29 

1/13 
1/34 
1/18 
1/11 
1/16 
1/32 
1/04 

i/aa 

1/23 

1/05 
1/05 
1/35 



1/23 

1/50 
1/51 
1/35 
1/15 
1/uu 
1/ai 
l/«3 
1/52 
1/07 
1/19 
1/39 
1/17 
1/20 



1/22 



1/09 

1/46 

1/33 



1/25 



1/31 



1/37 



Figure 8-2. Cross-Reference Listing 



Figure 8-2 shows the cross-reference from the entire 
program whose listing begins in Figure 8-1. 

The cross-reference lists the page and line number 
where each user symbol (such as a label) is defined, 
and the page and line number of each reference to this 
symbol. The column labeled "symbol type" indicates 
which symbols were externally defined or entered. We 
will explain symbol types when we discuss pseudo-ops. 

Symbols 

You use many kinds of symbols in an assembly- 
language program. Each machine language instruction 
is a symbol (like JMP for "jump to"), and some 
instructions use predefined symbols in their possible 
arguments (see Special Instruction Symbols described 
below). Other symbols are assembler pseudo-ops; also 
described below. Finally, you will want to create your 
own symbols. For example, you will want to name 
memory locations (e.g., START for the beginning of 
your program) so that you can refer to them 
symbolically instead of by their precise numeric address 
(e.g., JMP START instead of JMP 01762). 

Any symbols you create must be unique within a 
program module and must adhere to the following 
format: 

first character [succeeding characferfs) J break 

where the first character can be any letter from A 
through Z, including a period (.); succeeding characters 
can include A through Z, period (.), and numbers 



through 9. A break character is usually a space, tab, or 
carriage return. 

The Symbol column of Figure 8-2 shows some 
symbols. Others are: 

.DATA 

DATA 

FILE1 

BT000 

MESS1 

.MSG1 



While your symbols may be longer than five characters, 
for our purposes the assembler considers only the first 
five to be unique. Generally, your symbols should be 
five characters or less. 

You may not use a period (.) as a single-character 
symbol. The assembler reserves this symbol to mean 
the value of the current location in a program. For 
example, JMP .-I means "Jump to the current location 
minus 1." Nor can you use a number as the first 
character of a symbol name; e.g., 5TEST. 

If you follow these rules you may still receive an 
occasional assembly error indicating a bad symbol. This 
may happen because there are symbols (like error 
codes, that begin with ER; e.g., ERDNE) defined in 

certain system parameter files. You can always clear up 
such errors by simply modifying the offending symbol, 
perhaps by placing a period at its beginning or end. 
Assembly errors are described in an appendix of the 
appropriate Assembler user's manual. 
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Argument Operators 

From time to time, you may want to perform some 
operations on symbols. Typical operations include 
forming a byte pointer from a symbol name, and 
creating indexes in a table. For example, if START is 
the name of the beginning of a text string, 2 times 
START would be a byte pointer to the beginning of this 
string (the next chapter reviews byte pointer and bvte 
string concepts). Similarly, if TABLE is the name of the 
beginning of a table with one-word entries, then 
TABLE+ 1 would name the second entry in the table, 
TABLE + 2 the third entry in the table, etc. 

You may apply the following operators to symbols, 
integers, and the current location counter: ' 



Operator 

+ 



Arithmetic 



/ 



Meaning 

Addition (2 + 3) or unary plus 
( + 3) 

Subtraction, (5-2) or unary 
minus (-7) 

Multiplication 

Division 



Thus you could write JMP . + 5 to jump 5 words from 
the current location. If your program reserves a series 
of addresses whose first word is address TABLE 
indexes off TABLE wold be TABLE + 1, TABLE + 2 

etc. 

Numbers 

All numbers that you use in your programs are octal 
unless you specify otherwise. Indicate decimal values 
by placing a decimal point after the number. Thus 10 
equals octal 10 (decimal 8), while 10. equals decimal 10 



Instruction Types: 

Most Data General machine instructions assemble into 
one 16-bit storage word. There are three types of 
instruction: 

• Memory Reference Instructions (MR Is). M RIs concern 
memory locations or their contents. They permit 
one of four different kinds of indexing into these 
locations. The address they reference must fit in 8 
bits, because their address field is 8 bits long. 
Examples of MRIs are LDA 0, TEMP (load 
accumulator with the contents of address 
identified with label TEMP) JMP ER (Jump to the 
instruction identified by label ER). and JSR PRINT 
(Jump to subroutine PRINT, save return address in 
AC3). Some basic MRI instructions and [heir 
simplest formats are shown in Table 8-1. 

• Arithmetic-Logical Instructions (ALCs). ALCs can add 

and subtract values, shift bits, swap bytes, use the 
overflow (Carry), and redirect program execution. 
They can also AND values to mask portions of 
words. All ALC instructions require a source 
accumulator and a destination accumulator to 
receive the result of the arithmetic-logical operation. 
Examples of ALC instructions are MOV 0, 1 (copy 
the contents of AC0 to AC1) and SUB #0\ 1,SZR' 
(Subtract the contents of AC0 from AC 1, don't load 
AC1 with the result, skip the next instruction if the 
result is 0). Some common ALC instructions are 
shown in Table 8-2. 

► Input-Output (I/O) Instructions. I/O instructions 
govern the operation of all system devices. 
Generally, operating system calls will manage I/O 
devices, and you'll need these instructions only to 
write your own interrupt handlers, which are outside 
the scope of this book. 



Table 8-1. Common MRI Instructions 



Instruction and 
Format 

JMP addr 



Explanation 



JSR addr 



LDA ac addr 
STA ac addr 



Jump to address addr, which can be a symbolic or numeric address or 
expression. This definition of addr applies to ail instructions. 



Example 



Jump to addr, save return address (current addr + 1) in AC3. You can 
return from a JSR with a JMP 03 instruction (if the code to write you 
jumped didn't overwrite AC3). 



OSZaddr 



Load accumulator (ac) with contents of addr. 



JMPER 

JMP LOOP +6 

JMP 300 



JSRSUBR1 



Store the contents of ac in addr. 



Decrement the contents of addr by 1 , skip the next instruction if contents 
equal O. 



LDA O, MYF1L 



STA 3 LOOPO 



DSZ COUNT 
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Table 8-2. Common ALC Instructions 



Instruction and Format 


Explanation 


Example 


ADD [opt] acs acd [s] 


Add the contents of accumulator acs to contents of acd, place result in acd. 
opt is one or more of the carry, shift, or no-load options; s is an optional skip 
directive. 


ADD 2 


SUB [oprj acs acd [s] 


Subtract the contents of acs from acd, place result in acd. 


SUBO.O 


MOV [opt] acs acd fs J 


Copy the contents of acs into acd. 


MOV 2,0 


AND [opt] acd acs /s/ 


Logically AND the contents of acs with acd, place the result in acd. 


AND 1 



Special Instruction Symbols 

You can use certain symbols to modify the operation of 
certain arithmetic/logical and memory reference 
instructions as shown under the o/7/cateeory. in Table 
8-2. 

You can append one of the following one-character 
symbols (opt) as a suffix to arithmetic/logical (ALC) 
instructions to produce the following results: 

Opt Operation Result 

C complement Set the carry bit to the opposite of 
carry its current state before the 

arithmetic/logical operation. 

L left shift Combine the carry bit and the 

operand, and shift the 1 7-bit result 

one bit left, after the 
arithmetic/logical operation. 

O set carry Set the value of the carry bit to 1 

before the arithmetic/logical 
operation. 

R right shift Combine the carry bit and the 

operand, and shift the 17-bit result 
one bit right, after the 
arithmetic/logical operation. 

S swap Swap the left and right bytes for the 

arithmetic/logical operation. 

Z clear carry Set the value of the carry bit to 
before the arithmetic/logical 
operation. 



You may use the following 3-character skip symbols 
with arithmetic/logical instructions to perform 
single-word skip operations. These are shown as s in 
example formats. You must always place these symbols 
at the end of the argument list. 

Symbol Result 

SKP Unconditionally skip the next instruction. 

S2C Skip the next instruction if the carry bit equals 
0. 

SNC Skip the next instruction if the carry bit equals 



SZR Skip the next instruction if the result equals 0. 

SNR Skip the next instruction if the result doesn't 
equal 0. 

S8N Skip the next instruction if both the carry bit 
and the result are nonzero. 

SEZ Skip the next instruction if either the result or 
carry bit equals 0. 

You will see uses of these special instruction symbols in 
the example program in Chapter 9. 

Special Characters 

There are two special operations you can specify when 
using some machine language instructions: indirect 
addressing, and no-load of the result of 
arithmetic/logical operations. 



8-6 



069-000022-01 



In a source program line containing a memory 
reference instruction (such as LDA, load an 
accumulator; or JSR, jump to a subroutine, save return 
address), or before an expression, you may use the 
commercial at sign (@).An ©anywhere in a memory 
reference instruction argument sets bit 5 in that 
instruction, the indirect addressing bit. For example: 

024060 LDA 1,60 
026060 LDA 1,@60 

The first instruction loads accumulator i (AC1) with 
the contents of memory location 60; the second loads 
AC1 with the word whose address is in location 60. 
Likewise, using @ in a data word sets bit (the indirect 
bit for a data word) of that word to one: 

000025 25 
100025 ©25 

Like @, a number sign (#) may appear anywhere in an 
arithmetic/logical instruction. A #sets bit 12 of the 
instruction to 1; this is the no-load bit, and you use it 
with one of the arithmetic/logical instruction symbols 
when you want to test for equality, zero or other values 
without changing the value in the accumulator. 

133102 ADDL 1.2.SZC 
133112 ADDL# 1.2.SZC 

The first instruction adds the contents of AC 1 to AC2, 

places the result in AC2, and skips the next instruction 
if the carry bit equals 0; the second instruction does the 
same thing, but does not load AC2 with the result, in 
the first instruction, AC2 is loaded with the result; in 
the second, it is unchanged. 

The following examples show you how you can use 
special instruction symbols and special characters to 
modify the ADD instruction. 

Instruction Meaning 



Note that whenever you use the no-load (#) symbol 
you must specify one of the skip symbols (SZR, etc.) 
and specify a shift operation (L for shift left, R for shift 
right, etc.). The shift operation can be a dummy (e.g., 
SUB C, 0,0, SZR when you don't care about the carry 
bit) but it must be present for no-load to work. 

Pseudo-ops 

A pseudo-op instruction directs the operation of the 
assembler. It is called a "pseudo instruction" because 
your program never executes it. The pseudo-ops that 
you need to start assembly language programming are: 

Pseudo-op Function 

• BLK Reserve a series of 16-bit words. 



.END symbol Terminate a module and name a starting 
address 



.ENT Declare an entry point or symbol to be 

available for other modules' use. 



.EXTD Declare a symbol (unsigned 8-bit or 

signed 7-bit quantity) or page-zero 
(ZREL) entry point to be external; that 
is, found in some other module. .ZREL 
references are useful because they will fit 
into the 8-bit field of an MRI instruction. 



.EXTN Declare an entry point or 16-bit symbol 

to be external; that is, found in some 
other module. 



ADD 1,2 Add the contents of accumulator 

AC1 to AC2. 

ADDL 1,2 Add the contents of AC1 and AC2, 

shift the result one bit to the left, 

placing the carry in bit 15, and leave 
the result in AC2 and carry. 

ADDL 1.2.SZC Add the contents of AC! and AC2, 
shift the result one bit to the left, 
leave the result in AC2 and carry, and 
skip if this operation yields a zero 
carry. 

ADDL# 1.2.SZC Add the contents of AC1 and AC2, 

shift the result one bit to the left, and 

skip if this operation yields a zero 
carry. Do not alter the original 
contents of AC2. 



.NREL Assemble the following code and data for 

execution in normal-relocatable (NREL) 
memory. 



.TITL Assign a title to a module. 



.TXT Create an ASCII text string. 



.TXTM Specify text string byte packing (e.g., left 

to right). 



.ZREL Assemble the following code and data for 

execution in page zero (ZREL). 
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Often you will want to refer to a symbol or call a 
subroutine which is defined outside the module you are 
writing. To do this, you must name the symbol or entry 
point in an .EXTD or .EXTN pseudo-op.*. EXTD 

symbols are limited to 8 bits, and .EXTN symbols are 
16 bits long. That is, you could write 

.EXTD A 
LDAO.A 

without receiving an assembly error, but 

.EXTN A 
LDAO.A 

would receive an assembly error (LDA is an MRI 
instruction with an 8-bit displacement field). Each 
argument that you name in an .EXTN or .EXTD 

pseudo-op must be made available with an .ENT 
pseudo-op in another module that you will load with 
this module. 

The .TXT pseudo-op assembles a character string into 
its equivalent ASCII codes (two per word), terminated 
by a null byte packed right to left. Insert a ".TXTM 1" 
pseudo-op at the beginning of the program to pack 
bytes left to right. You can use any character not in the 
string as string delimiters. Thus, 

.TXTM 1 



.TXT"ABCDE" 



stores the ASCII codes for A and B in the first word, C 
and D in the second, and E < null > in the final word. 
Text (.TXT) strings can contain lowercase letters. 

TITL assigns a title to a module (do not confuse the 
title with the module's filename). The module's title 
appears on the top line of each page of the module's 
assembly listing. 

.ZREL starts assembly storage from the first available 
ZREL location (location 50 s by default). ZREL storage 
extends through 377 g , and is directly addressable by all 
instructions. .NREL starts assembly storage at the 

beginning of NREL memory. 

Now that we have described certain assembler 
pseudo-ops, we can explain the third column of each 
assembly-listing cross-reference (see Figure 8-2). This 
column contains two-letter codes describing the types 
of symbols which have been the argument of certain 
pseudo-ops. 

Code Meaning 

EN entry (.ENT pseudo-op) 

XD external displacement (.EXTD pseudo-op, not 
shown in Figure 8-2) 

XN external normal (.EXTN pseudo-op) 

There are other codes, outside the scope of this 
discussion, which refer to pseudo-ops that we have not 
described. 
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.BLK 



.END 



Allocate a Block of Storage 



Indicate the End of a Module 



Format: 

.BLK expression 

Description: 

This pseudo-op allocates a block of memory storage. 
Expression is the number of words you want reserved; 
the current location counter is incremented by 
expression. 

Examples: 

TABLE:. BLK 10. 

This example reserves a block of ten memory words; 
the first word in the series has the symbolic name 
TABLE, the second TABLE + 1, and so on. 



Format: 

.END [expression] 

Description: 

This pseudo-op terminates each assembly language 
module. If the program you are building has several 
modules, one of these modules must supply an 
expression argument to .END indicating the address to 
receive control when the program is executed. ASM 
requires a .END for each module; MAC does not. 

Examples: 

START: SUB 0,0 



.END START 

In this example, the .END pseudo-op terminates the 
module and defines START js the address that will 
receive control when you run the program. 
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.ENT 



Define a Module Entry 



Format: 

.ENT symbol {symbol...] 

Description 

This pseudo-op declares symbols defined within the 
module to be available for referencing by other 
separately-assembled modules. Each symbol must not 
only be unique from other symbols within the module 
(this is always a requirement), but it must be unique 
from entries defined in other modules that you process 
together to form a single program. 



Other modules use the .EXTN pseudo-op to reference 
symbols defined by the .ENT pseudo-op. 



In this example, PROGA is the main program. It can 
call two external routines in module TRIG: SINE and 
COS. The pointer .SINE is required because JSR is a 
memory reference instruction with an address field of 8 
bits. .SINE must be within 127 words of the JSR. SINE 
can be anywhere in the program since the word SINE in 
.SINE:SINE has 15 bits available for addressing. 



Examples: 





.TITL 

.ExTN 

.TXTM 


PRUGA ; proga i s ffa } n mcau1e 

SINE, CCS ; SIf.E, COS ere "in rrcoule TRIG. 




.NPEL 






START: 


. 




PROGA initializes thincs here 
and does its o*n p recess inp 




• 


; 


until it neeos routine SINE or COSINE. 


.SINE: 
.COS: 


JSR 3 .SINE I JSR to SINE 'in c t he r _ rroou 1 e . 

• t Return here arc continue. 
JSR i .COS ;-JSR to CCS fn other rrcoule. 

# "> Return here ana-continue. 
SIN£ ' Aaoress in th e moaule. 
COS ; Ditto. 

.END START 




.TITL TRIG 
A hi SINE* 
•TxTM 1 


« TRIG aces tr'iq. 
COS ,* I o e n t i f y e r t r i e 6 . 




.NREt 







SINE 



CCS: 



STA I, (JSP ; Save return ecor in t S P , 

I safe ZREl ssoreis 

i Described later, 

» > SINE crocessirc routine 

I is here, uses A C 3 » 

I Done# restore return aocr, 

t Return t o P R C G 1 . 

# Save return, 

t Do COS Processing. 

? Restore return soar, 

$ Return to PRCG1. 



IDA 
8TA 
LDA 
.END 



I, L'SP 
I, 5 

I, L'SP 



I, USP 

e, 5 
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.EXTD 



Declare an External Displacement 



Format: 

.EXTD symbol [symbol...] 



will use .EXTD when ihe symbol is defined in another 

module's ZREL space. 



Description: 

This pseudo-op declares that one or more symbols 
referenced by this module are defined (.ENTered) in 
other modules. The value of the symbol must be an 
8-bit quantity; e.g., a ZREL address. Generally, you 



Here, the ERR routine in module MAIN is available to 
module MODI through a pointer in MAIN'sZREL 
space. This allows the assembler to resolve ERR's 
address for the JSR instruction (which it could not 
otherwise do because JSR's address field is only eight 
bits). All of a program's ZREL space (locations 5(K377 S ) 
is accessible to the eight bits of an MRI instruction. 



Example: 



.TITL MAIN ; Main prccram. 

.ENT .ERR ; Error handler is here. 

.EXTN F00 ; F00 code is in other module 

.TXTM 1 



.ERR: 


.ZREL 

ERR 




»* ERR definec in MAIN*s Z 


START: 


.NREL 
LDA 


... / 


MAIN'S NREL 




• 


; 


cooe is Here. 


ERR: 


• 


; 


Error hjno 1 e r , 




.END 


START 






.TITL 

• ENT 


MODI 

= 00 


; Mooul e MODI . 




.EXTD 


.ERR 


> .ERR definec in 




. TXTM 


1 


'> another module's ZREL. 


FOO: 


.NREL 
LDA », 




» MODI ' s cooe i s 




jsr a 


.ERR 


', here. 

1 Use .EXTD error 

1 handler. 




• END 
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.EXTN 



.NREL 



Declare an External Reference 

Format: 

.EXTN symbol [symbol...] 

Description: 

The pseudo-op declares that one or more symbols 
referenced by this module are defined (.ENTered) in 
other modules. Note that the symbol can be a 16-bit 
quantity. 

Examples: 

See the .ENT example. 



Set the Location 
Normal-relocatable Code 



counter 



to 



Format: 

.NREL 

Description: 

This pseudo-op sets the location counter to the next 
available word of normal-relocatable memory. It is 
normally required in each module. 

Examples: 



T1TLPROGB 
TXTM 1 
ENTINIT 
EXTNSCRT3 

NREL ;Normal relocation from now on. 
INIT:LDAO, FILEA 



ENDINIT 
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.TiTL 

Entitle a Binary Module 

Format: 

.TITL symbol 

Description: 

This pseudo-op gives an RB module a title, which is 
printed at the top of every listing page. The title need 
not be different from other symbols in the module. The 
title has no inherent relationship to the module's 
filename, although you might want to use the same 
names for clarity. 

Examples: 

.TITL EXAMPLE 
.NREL 



.END 



This example assigns the title EXAMPLE to this 
module and prints EXAMPLE at the top of each listing 
page. (The assembler, which considers all symbols to 
be unique within the first five characters only, will 
discard the "LE' 1 of "EXAMPLE"; the listings will 
start with "EXAMP") 



.TXTM 




Specify .TXT Byte Packing 


.TXT 





Create a Text String 



Formats: 

.TXTM number 
.TXT u string u 

Description: 

Normally, the assembler packs bytes right to left - 
which is the wrong order for ASCII text strings and 
other required items. To correct this, insert a .TXTM 1 
statement before the TXT appears in your program. 

The .TXT pseudo-op creates an ASCII string, which 
can contain any ASCII characters. You must delimit the 
text with a character that is unique (u);that is, not 
found in the string. You can put nonprinting characters 
in the string by enclosing them within angle brackets. 

Examples: 

.TXTM 1 



.TXT"ABCDE" 

This example creates the ASCII string consisting of 
three words. The first contains the letters AB, the 
second contains the letters CD, and the last word 
contains an E in the left byte and a terminating null in 
the right byte. 

TXT'*AB<011 >CDE" 

This example creates the ASCII string consisting of AB 
and CDE, separated by a horizontal tab (ASCII code 
Oil). 
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.ZREL 

Set the Location Counter to Page Zero 

Format: Description: 

• ZREL This pseudo-op sets the location counter to the next 

available word in lower page zero. This is initially 
location 50 8 . 



Example: 





000001 


. TIU PROGC 

.TXTM 1 






00000.06555a 


.ER: 


.ZREL 
ERR 


; 


ZREl pointer to 










; 


error hardier. 


00000 

e- e b 3 1 

00302 
00003 


2 a 5 u 
00601 7 

1 « 
002000 


1 n I t : 


.NREl 

LDA 0, Mw 

.SYSTN' 

.OPEN 
J M P o? .ER 


» 


NREL coce bea'ins 

System c«l 1 
aheys needs 
error return. 


* 


* 




* 




Bccy of proprair. 



fc555a e0b0l7 ERR: . ; Error hencler ccae 

', becins et eodr fc 5 5 5 « , 

', yet is accessible via 

i ZREL frcf anywhere \ n 

S 3 ? * J e.o.» location 3, 

.END IMIT 



End of Chapter 



8-14 

w 069-000022-0* 



Chapter 9 
Programming RDOS or DOS 
Assembly Language System Calls 



This chapter first introduces some operating system 
calls, with examples, and then shows the examples 
coded into a viable program. We'll then write an 
assembly language program, assemble it, correct 
assembly errors, process it with RLDR, and execute it. 
We will finish this chapter by showing you how to 
debug the program. 

Operating System Conventions 

Most Data General computer words are 16 bits long, 
and bit positions are numbered left to right, to 1 5 
inclusive. A byte is 8 bits long. A byte string consists of 
a sequence of bytes, packed right to left in series of one 
or more words. A byte pointer consists of a single word 
with two fields (see Figure 9-1). To pack bytes left to 
right, as required for system calls, insert a .TXTM 1 
statement at the beginning of the program. 



1 : „ "-■'':■ K ' 



' H 






SO-00526 



Figure 9-1. Byte Pointer Structure 



The left field (bit positions through 14) contains the 
address of the word that holds the selected byte. When 
right field (bit 15) equals 1, the pointer selects the right 
half, or byte; when this bit equals 0, the pointer selects 

the left byte. You can produce a byte pointer by 
multiplying the address at which it begins by 2; this 
shifts all bits left and zero (which specifies the left byte) 
in bit 15. 



Here is a byte pointer example: 
.TXTM 1 



BPTR: 



. + 1*2 
.TXT"STTI* 



. + 1 is the address of the next location - the start of text 
string STTI. The label BPTR contains the start address 
of the text string. The multiplier *2 zeros bit 15, 
thereby specifying the first byte, S. 

System Call Format 

Code each system call in the form: 

.SYSTM 
cafi-name 
error return 
normal return 

You must precede the call with the mnemonic 
.SYSTM, and reserve a word after the call for the error 
return, which receives control on either an error 
condition, or an unusual condition such as an 
end-of-file. You must always reserve an error return 
word, even if you envision no possible exception 
condition, or even if no condition is currently defined. 
If no error or exception condition exists, control goes 
to the normal return. 

Whenever control goes to the error return, the system 
places a numeric error code in AC2. These error codes 
are defined in the user parameter file. PARU.SR and 
they are explained in Appendix A of your system 
reference manual. 

Upon either an error return or a normal return, AC3 
contains the current contents of location 16 g , the user 
stack pointer. You can use this location as you want. 
Unless the text indicates otherwise, all other 
accumulators will remain unchanged. 
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Some system calls require you to pass a byte pointer 
(Figure 9-1) in ACO; some of these need other data in 
ACL 

All system calls are executed in system address space; 

/asA- calls, not described here, are executed in your own 
space. You must not use memory locations 0-15, or 
I7„; the system uses these locations for calf processing. 

Operating System Call Summaries 

As we have done throughout this book, we will 
describe only the most important aspects of these calls. 
After you have mastered the techniques for using these 
simple versions, you may want to use the more 
complex versions. For many applications, however, the 
simple versions of these calls will suffice. 

The calls we describe here are: 

.GRAND Create a random file. 

.OPEN Open a file or device for reading or writing. 

.APPEND Open a file or device for appending. 

.RDL Read a line. 



.GRAND 



.WRL 



Write a line. 



.RTN Stop the program and return to the CLI. 

If your program will execute I/O transfers, it must 
follow this sequence of operations: 

1 ) Open the file or device on a channel via an .OPEN 
or .APPEND call. The program will use the channel 
number, not filename or device name, for ail I/O to 
the file or device. 

2) Read or write data to the channel (.RDL or .WRL) 

.RTN will close open files, terminate the program, and 
return to the CLI. 

If a call takes the error return to your program, AC2 

will contain an appropriate error code. The sample 
program we've devised uses system call .ERTN to ask 
the CLI to print an appropriate error message on the 
console. 



Create a Random File 



.CRAND creates an empty random file in the current 
directory. 



Format: 

.SYSTM 
.GRAND 
error return 
normal return 



Required Input: 

ACO - byte pointer to the filename of the new file. 

Return: 

ACO - unchanged. 
ACI -unchanged. 
AC2 - error code. 



Example (within a program): 



LDAO.MYFIL 

.SYSTM 

.GRAND 

JMP ER 

;NORMAL RETURN. 

MYFiL: . + 1*2 ;BYTEPOINTER. 

TXT "OUTPUT" 
ER: .SYSTM 



.ERTN 



.ERTN TELLS THE CLI TO 
DISPLAY THE REASON 
FOR THE ERROR RETURN. 
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OPEN 



Open a File for Reading or Writing 



.APPEND 



Open a File for Appending 



.OPEN associates a file with an I/O channel and opens 
it for any kind of I/O. .APPEND associates a file with 
an I/O channel and opens it for writing only. If the file 
is an output device like a line printer, .OPEN and 
.APPEND are practically identical. For a disk file, if you 
open via .OPEN, lines are written to the beginning of 
the file. If you open via .APPEND, reads aren't allowed 
and lines are appended to the file. 

While the file is open, your program references it by 
the channel number assigned in the open call. It keeps 
the channel number until the program issues .RTN or 
.CLOSEs it. We do not describe .CLOSE in this book 
because the .RTN or .ERTN calls automatically close all 
channels. 

You can allocate a number of channels (and tasks) to a 
program in the RLDR command line. If you omit 
channel and task data entirely, the program receives 
one task and eight channels; this will suffice for the 
program in this chapter. 



Return: 

AC2 -error code. 



Format 

.SYSTM 
.OPEN/? 

or 

.APPEND n 
error return 
normal return 



; n is the I/O channel number 



Required input: 

ACO - byte pointer to the file or device to be opened. 

AC1 - if the file is a device, AC1 acts as a characteristic 
disable mask. You'll probably want to keep the 
default characteristics by setting AC! to (via a 

SUB # 1,1 instruction). 



Example (within a program): 



This program just created the file "OUTPUT' 



LDA 0, NTTI 


;BYTE POINTER TO 




CONSOLE 




;INPUT FILENAME. 


SUB 1,1 


;USE DEFAULT MASK FCR 




OPEN. 


.SYSTM 


;0 IS THE I/O CHANNEL 




NUMBER- 


.OPENO 


;WHILE THE STTI IS 




;OPENON0, 




;YOU'LL ADDRESS IT 




;AS0. 


JMPER 


;ER WAS DEFINED 




EARLIER. 


LDA 0, OUTPUT 




SUB 1,1 


;DEFAULTMASK. 


.SYSTM 




.APPEND 1 


;OPEN "OUTPUT" 




;FOR APPENDING ON 




iCHANNEL 1. 


JMPER 




NTTI: . + 1*2 




.TXT "STTI" 


FILENAME STTI. 


OUTPUT: . + 1*2 




.TXT "OUTPUT" 
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.RDL 



- I 



WRL 



Read a Line into Memory from a File or 
Device 



Write a Line from Memory to a File or 
Device 



Use this command to read an ASCII line from a file 
opened on a specified channe! into a memory area 
(which should be 133 bytes long). Reading will 
terminate when the system reads a carriage return, 
form feed, or null. If the program is reading from the 
console keyboard (filename STTI), you can indicate an 
end-of-read by typing }. 

Format: 

.SYSTM 

.RDL n ; Read from the file on channel n. 
error return 
normal return 

Required input: 

ACO - byte pointer to the 1 33-byte line buffer area. 



This command writes an ASCII line to a file opened on 
a specified channel. Writing stops when the system hits 
a carriage return, form feed, or null. The system writes 
the line to the beginning of a disk file if you .OPENed 
it. If you opened il via .APPEND, the system appends 
the line to material already in the file. 

Format: 

.SYSTM 

.WRL/? ; Write to channel n. 

error return 
normal return 



Require input: 

ACO - byte pointer to memory area from which the line 
will be read. 



Return: 

AC1 - byte count of characters read, not including 
terminator. 

AC2 - error code. 



Example (within a program): 

This program just .OPENed the TTI and opened 
"01^1;^ for appending. 



LDAO, SPACE 

.SYSTM 

.RDLO 

JMPER 



SPACE: .4-1*2 • 
.BLK67. 



;DEFINED EARLIER. 

;RESERVE 67 WORDS 

(134 BYTES) 

;FOR THE LINE. THE 

PERIOD 

INDICATES A DECIMAL 

FIGURE 

;T0 THE ASSEMBLER. 



Return: 

ACI - byte count of characters written, including 

terminator. 
AC2 - error code. 



Example: 

This example writes the line read from the console bv 
.RDL to file "OUTPUT". 



LDAO, SPACE 
.SYSTM 

.WRL 1 

JMPER 



SPACE WAS DEFINED 

EARLIER 

WRITETO FILE "OUTPUT" 

ON CHANNEL 1. 
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.RTN or .ERTN 



Return to the Program Above 



RDOS and DOS offer five levels of program operation; 
the CL1 normally operates on level 0, and any program 
you execute from the CLI executes on level \. 

By ending your program with .RTN (or .ERTN), you'll 
return control to the CLI when the program has 
executed. If you omitted .RTN (or .ERTN), you'd 
need to hit an interrupt like CTRL-A to return the CLI. 
but this lacks finesse. 

Call .RTN simply returns control to the CLI, while 
.ERTN passes the contents of AC2 to the CLI. On a 
system call error, the system places an identifying error 
number in AC2. So, if a program issues .ERTN when a 
call error occurs, the system will pass the error code to 
the CLI; the CLI will interpret the number returned in 
AC2 and type an explanatory message on the console. 
Thus .ERTN is generally useful as an error handler, as 
shown in the .GRAND example. 



error number in AC2, then goes to the error return. 
You can have an error processing routine examine this 
number and act on what it finds. The "mnemonic"' 
shown next to the error number means the same thing 
as the number; it is defined in the system parameter 
file, PARU.SR, and you can use it instead of the 
number if you insert PARU/S (PARLVScan) in the 
assembler command before the program filename; e.g., 
ASM PARU/S filename }. 



Error on call was: 

Illegal channel number. 
Illegal filename.' 
End of file. 
File already exists. 
File does not exist. 
File not open. 



AC2 


Mnemonic 





ERFNO 


1 


ERFNM 


6 


EREOF 


11 


ERCRE 


12 


ERDLE 


15 


ERFOP 



Format: 

.SYSTM 

.RTN (or .ERTN) 

error return 



Required input: 

None. 



Example Program 

The example program, called WRITE, is a short 
assembly language program that goes through the 
standard I/O cycle and uses three files: a disk file 
named W, the console output file (reserved filename 
STTO) and console input file (reserved filename 
STTI). 



Example (to terminate our little program): 

.SYSTM 

.RTN 
JMPER 

Common Errors 

The following errors are the most common ones that 
can occur on the system calls we have shown. If one of 
them occurs, the system places the appropriate octal 



If disk file W doesn't exist, WRITE creates it; then 
WRITE opens all three files and prompts you with a 
question mark. It accepts a line typed on the console, 
and, after you press } to end the line, writes the line to 
disk file W and echoes the line on the console. It then 
prompts you again. WRITE opens W for appending via 
call .APPEND, which means that all lines you type will 
accumulate in file W, When you type a special 
terminating line (&)), WRITE returns to the CLI. 
Figure 9-2 is the flowchart for program WRITE. The 
slashed numbers are page/line abbreviations; e.g., 1/12 
means page 1, line 12. 
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Writing and Assembling WRITE.SR 

The following pages show WRITE and analyze it line by 
line. They show listing lines as page/tine; e.g., 1/6 
means page 1, line 6. You might want to examine 
WRITE in Figure 9-3 before reading the next 
paragraph. 

If you want to try WRITE, you'll need a number of 
utility files, so begin in the master directory. Use 
Superedit to create a file named WRITE.SR and type in 
all the instructions shown in the program listing in 
Figure 9-3. This is an assembler listing so dott'nype in 
any of the numbers or punctuation in columns 1-16. It 
might help you to pencil a straight line down the 
beginning of the instruction field (e.g., from the space 
before .ER: down to the space before .ERDL on the 
first page of the listing) and use this as a guide. 

If you have an upper- and lowercase console, you can 

code in either. The most legible way is to put source 
code in CAPITALS and comments and text strings in 
upper- and lowercase. The assemblers don't care what 
case you use, but legibility is important. 

When you've finished typing in WRITE, close the file 
(UESHSS). 



Assembling WRITE 

You can choose between the ASM and MAC 
asemblers for WRITE. We have used MAC for the 
listing shown, but either one will work. 

To use ASM, type: 

ASM/X PARU/S WRITE SLPT/L} 

or, if you don't have a line printer, type: 

ASM/X PARU/S WRITE STTO/L) 

If your printing terminal is connected to the second 
teletypewriter interface, type STTOl/L instead of 

STTO/L. From either ASM command, you should get 
a listing like the one in Figure 9-3, but without the 

MACRO header. Although the paging will differ a 
little, the critical locations are the same. 



If, as we did, you want to use the MAC assembler, you 
may need to build the permanent symbol file for it. 
Generally, this is needed only once; MAC then uses it 
for all future assemblies. Try typing: 

MAC PARU/S WRITE} 

If you get U or F errors on instructions like LDA or 
.SYSTM, then you must build a new MAC. PS. This is 
easy to do. 

If you have a NOVA 4 computer, type: 

MAC/S NBID OS1D NS1D N4ID PARU) 

For a NOVA 3, type: 

MAC/S NBID OS1D NSID PARU} 

For a microNOVA, type: 

MAC/S MB!D OSID NSID PARU} 

For other NOVA computers, type: 

MAC/S NBID OSID PARU) 

For ECLIPSE machines, type: 

MAC/S NBID OSID NE1D PARU} 

The proper command creates MAC. PS for your 
machine; you need not create MAC. PS again for this 
book. Other source (-.SR) files you may eventually 
need for the Macroassembler are described on the 
Release Notice supplied with your system. 

Having checked (or built) MAC. PS, type: 

MAC WRITE SLPT/L} 

or, lacking a line printer, type: 

MAC WRITE STTO/L} 

for a console listing. If your printing terminal is 
connected to the second teletypewriter interface, type 
STTO 1 /L instead of STTO/L. From either M AC 
command, you should get a listing like the one in 

Figure 9-3, plus the cross-reference. 



069-OOO022-O1 



9-7 



0001 hRITE 



GU 

03 

04 

05 

06 00000 

07 

08 
09 
10 
11 

12 00000 

13 00001 

14 00002 

15 00003 
U00804 

17 00005 
38 00006 

19 00007 

20 00010 

21 00011 
22 

23 00012 

24 00013 
25 

26 
27 

28 00014 

29 00015 

30 00016 

31 00017 

32 00B20 

33 00021 
3a 00022 

35 00023 

36 0002a 

37 00025 

38 00026 

39 00027 
a0 00030 

41 00031 

42 00032 
a3 00033 

uu 0003a 

45 00035 

«6 00036 

47 00037 

4 8 

49 

50 

51 

52 

53 000411 • 

5« 000C2 1 

55 000fi3» 

56 00044' 

57 000«5» 

58 000efc' 
U000«7« 

60 00050' 



000001 
-000175 



020454 
■006017 

0i2a00 

000436 

020000 

126400 

006017 

0ia001 

002000- 

028451 

006017 

014002 



•020452 

'006017 

•017001 

«002000« 

•020451 

•006017 

•0l5a02 

•002000- 

•030aa6 

«02aai2 

•132405 

»8ge«22 

•006017 

•017000 
•002000- 
•006017 
•017001 

« 002008- 

•000756 

•023015 

000008 



MACRO REV 06.30 

.TITL fcRITE 
.ENT START 
.TXTM 1 



.ERi 



»ZREL 
ERROR 

.NREL 



I Open the three f 1 lei, 

.STARTS LDA 0, NW 
.SYSTM 
.APPEND 
JMP NOFIL 
LDA 0, NTTO 
SUB 1, 1 
.SYSTM 
.OPEN 1 
JMP 3 .ER 
LDA 0, NTTI 

.SYSTM 
.OPEN 2 

; Begin the main progran 

LOOP! IDA 0, PROMT 

.SYSTM 

»hRL 1 

JNP 2 ,ER 

LDA 0, SPACP 

.SYSTM 

.RDL 2 

JMP 2 .ER 

LDA 2, SPACE 

LDA 1, ThORD 

SUB 1, 2, SNR 

JMP TOCLI 

.SYSTM 

.WRL 

JMP 3 .ER 

.SYSTM 

,*RL 1 

JMP S .ER 

JMP LOOP 
TfcORD; .TXT "&<15>" 



16j03!07_0a/02/79 

r Title is optional but sometimes useful. 

» Global entry for debugging, 

; Pack text bytes left to right. 

\ Pointer in page zero avoids assembler A error, 

; ,ER contains "ERROR" address in NREL space. 

\ New for the code proper. 



Point to ofsk filename h. 

System, 

open file W for append on channel 0, 

Error on APPEND, go to NOFIL -routine. 
Point to consols output filename. 
To open a device, use default disable mask. 
System, 
open console output on channel 1. 

Error return vie ZREL pointer to CLI. 
Point to console input (keyboarc) filename. 
Default mask; AC1 sti 1 1 s 0. 
System, 
open console keyboard on channel 2. 

1 OOP. 

Point to prompt character. 

System, 

write prompt to channel 1 (conicle out). 

Error - report v i a _ C L I . 
Point to beginning of line buffer. 
System, 
read a line from channel 2 (console keyboard) 

Error - report via CLI, 
Get 1st herd (2 bytes) of line buffer in AC2. 
Put terminator *ord {S.J) in AC1. 
here 1st 2 bytes U 1 (Skip "if not.) 

Yes -- return to CLI. 
N e _ » - System, 
write line to channel 0, file h. 

Error -- report. 
System, 
echo the line on console out. 

E r r o r _ - - report. 
New oo it ell again. 
Terminator *ore, I in left byte, CR in right. 



i Error processing routine r creates file * if it doesn't exist. hhen 
t system gets here, AC8 still has h pointer, AC2 hat error number. 



020407 

146404 

082080- 

806017 

087808 

082800- 

800008 

008812 



NOFIL? LDA 1, .ERDL 
SUB 2, It SZR 
JMP 3 »ER 
.SYSTM 
.CRAND 

JMP a .er 

JMP START 

.erdl: erdle 



I Gtt coae ERDLE (file ooes not exist), 

; Skip next instruction if file already exists, 

I Error other than ERDLE, exit, 

I System, 

I create file h . 

} Error, exit »nd report, 

i New go back enc open the new file, 

1 ERDLE s 12, 



Figure 9-3, WRITE, SR Program with Errors 
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/Normal return to CLI. 



8002 URITE 
01 
02 
03 000Si'0060l7 TOCLI: .SYSTM 

8« 0aa52*00«a00 .rtn 

05 00053*002000- j«wp a .ER 
06 

7 J Filenames, prompt, buffer 

08 



I System, 

; return to CLI. 

# Error (can't happen). 

etc. 



09 0005il«000i32"Nws 

10 000S5 , 053«00 
11 

FU00056'000000 NTTO 
13 00057«022i2a 
1« 052060 

15 000000 

16 00062»000i«6"NTTlj 

17 00063*022124 

18 052111 

19 00ee00 

20 

21 00066*000156"PROMT; 

22 00067'037ai5 

23 000000 

2a 

25 00071 '000164"SPACP: 

26 

27 00072»000103 SPACE; .BLK 132. /2+1 

28 

29 

30 ; Error return to CLI. 

31 

32 00175»006017 ERROR? .SYSTM 

33 00176*006400 .ERTN 

3« 00177'002000- JMP 3 .ER 
35 
UU .END START 



.♦1*2 
.TXT "W" 

. + 1*2 

,TXT "STT0' 



.♦1*2 

.TXT "STTI" 



.♦1*2 
.TXT »?<15> n 



I Point to filenime W. 
I Point to f i lename STTO. 



J Point to fil ename STTI, 



; Point to prompt 
; "?" anc CR U) . 



SPAC£*2 



; Point (aaor*2) to 1st byte in line buffer, 

# 133. bytes for read/write line buffer- 
i let the assembler compute "it. 



J System, 

", return to CLI and have CLI report. 

; Error (can't happen). 



**00008 TOTAL ERRORS, 00000 PASS 1 ERRORS 



Figure 9-3. WRITE.SR Program with Errors (continued) 



The program .ENTers its starting address, START, not 
because other modules will use ii, but because we want 
to identify START symbolically to the debugger. Later 
this will help us debug the program. The .ENT fine is 
flagged with a GU error. 



The .ZREL pointer on line 1/5 points to error handler 
ERROR at the end of page 2. Through this pointer, any 
location in 32K words can get to ERROR. Without the 
pointer, ERROR would be nearly out of range of the 
JMP in line 1/20. All system calls except the first, 
.APPEND, make use of this .ER pointer for their error 
returns. 



The .NREL in line 8 specifies normal relocation, which 
applies to the rest of the program. 



The first group of code, in lines 1/12-1/24, opens disk 
file W for appending and opens the console output and 
input files for normal I/O (line 16 has a U error). If 

.APPEND cannot open file, it takes the error return on 
1/15; thisjumps to the routine on lines 1/52-1/60. This 
routine creates file W if it doesn't exist, then jumps 
back to the beginning of the program. 

The next block of code starts with LOOP and extends 
from line 1/28 to line 1/48. This code reads a line typed 
on the console, and checks to see if the first two 
characters are & and ). It does this by loading the first 
two words (two bytes or two characters) from line 2/25 
and comparing this to a match word (1/47) set up to 
contain & }. If they match, the program returns to the 
CLI via sequence TOCLI, 2/3. If they don't match, the 
program writes the entire line to disk file W, echoes it 
on the console, and returns to LOOP. 
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Writing and Assembling WRITE. SR 

The following pages show WRITE and analyze it line by 
line. They show listing lines as page/line; e.g., 1/6 
means page 1, line 6. You might want to examine 
WRITE in Figure 9-3 before reading the next 
paragraph. 

If you want to try WRITE, you'll need a number of 
utility files, so begin in the master directory. Use 
Superedit to create a file named WRITE.SR and type in 
all the instructions shown in the program listing in 
Figure 9-3. This is an assembler listing so don't type in 
any of the numbers or punctuation in columns 1-16. It 
might help you to pencil a straight tine down the 
beginning of the instruction field (e.g., from the space 
before .ER: down to the space before .ERDL on the 
First page of the listing) and use this as a guide. 

If you have an upper- and lowercase console, you can 

code in either. The most legible way is to put source 
code in CAPITALS and comments and text strings in 
upper- and lowercase. The assemblers don't care what 
case you use, but legibility is important. 

When you've finished tvping in WRITE, close the file 
(UESHSS). 



Assembling WRITE 

You can choose between the ASM and MAC 
asemblers for WRITE. We have used MAC for the 

listing shown, but either one will work. 

To use ASM, type: 

ASM/X PARU/S WRITE SLPT/L) 

or, if you don't have a line printer, type: 

ASM/X PARU/S WRITE STTO/L) 

If your printing terminal is connected to the second 
teletypewriter interface, type STTOl/L instead of 

STTO/L. From either ASM command, you should get 
a listing like the one in Figure 9-3, but without the 
MACRO header. Although the paging will differ a 

little, the critical locations are the same. 



If, as we did. you want to use the MAC assembler, you 
may need to build the permanent symbol file for it. 
Generally, this is needed only once; MAC then uses it 
for all future assemblies. Try typing: 

MAC PARU/S WRITE) 

If you get U or F errors on instructions like LDA or 
.SYSTM, then you must build a new MAC. PS. This is 

easy to do. 

If you have a NOVA 4 computer, type: 

MAC/S NBID OSID NSID N4ID PARU) 

For a NOVA 3, type: 

MAC/S NBID OSID NSID PARU) 

For a microNOVA, type: 

MAC/S MBiD OSID NSID PARU) 

For other NOVA computers, type: 

MAC/S NBID OSID PARU) 

For ECLIPSE machines, type: 

MAC/S NBID OSID NEID PARU) 

The proper command creates MAC. PS for your 
machine; you need not create MAC. PS again for this 
book. Other source (-.SR) files you may eventually 
need for the Macroassembler are described on the 
Release Notice supplied with your system. 

Having checked (or built) MAC. PS, type: 

MAC WRITE SLPT/L) 

or, lacking a line printer, type: 

MAC WRITE STTO/L) 

for a console listing. If your printing terminal is 
connected to the second teletypewriter interface, tvpe 
STTOl/L instead of STTO/L. From either MAC " 
command, you should get a listing like the one in 
Figure 9-3, plus the cross-reference. 
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0001 hRITE 



MACRO REV 06.30 

.TITL *RITE 
,ENT START 
.TXTM 1 



GU 

03 000001 
?,ti 

05 

06 00000-000175* ,ERi 

07 

08 

09 

10 t Open the three fflei, 

11 

12 00000*028d5« .STARTS LDA 0, NW 



.ZREL 

ERROR 

.NREL 



16s83i07_0«/82/79 

; Title is optional but sometimes useful. 

» Global entry for debugging. 

i Pack text bytes left to right. 

I Pointer in page zero avoids assembler A error. 

J .ER contains "ERROR" address in NREL space. 

I New for the code proper. 



13 00001 '-006017 

Id 00002«012(j00 

15 00003*000(136 

U0000««020000 

17 00005» 126*108 

18 00006*006017 

19 00007'0H001 

20 88810*002000- 

21 00011'028«5l 
22 

23 00012*006017 

24 00013*01(1802 
25 
26 
27 
26 000H*020«52 LOOP! 

29 008S5'006017 

30 0001b'0l7001 

31 00017*002000- 

32 00028*020(151 

33 00021 '806017 
3d 00022*015(102 

35 00023*002000- 

36 0002« , 038(J«6 

37 00025*02«dl2 

38 00826* 132^05 

39 08027*0i8fi22 
d0 00030*006017 
Ul 00831*017080 
«2 08032'082800- 
«3 08833*006017 
UU 0003(1*017081 
«5 88035*002000- 
«6 00036*080756 

«7 00837*823015 TfcORD; 

UB 088000 

«9 

50 

51 

52 

53 800«i *02fld07 NOFIL? 

5d 800(,2* ia6«0d 

55 080a3'0e2888- 

56 800(i(l»006817 

57 880(l5 , 007800 

58 808«fc*0e280e- 
U800«7»008000 

60 08050»8B0012 .ERDL: 



.SYSTM 
.APPEND 8 
JMP NOFIL 
LDA 0, NTTO 
SUB 1, 1 
.SYSTM 
.OPEN 1 
JMP 3 ,ER 
LDA 0, NTTI 

•SYSTM 
.OPEN 2 



; Point to cisk f i lename H. 

; System, 

; open file W for append on channel 0, 

/ _ Error on APPEND, go to NOFIL rout 1 ne. 

; Point to console output filename. 

I To open a Device, use default disable mask. 

r System, 

; open console output on channel 1. 

I Error return vie ZREL pointer to CLI. 

; Point to console input (keyboarc) filename. 

, Default mask; AC 1 sti 11=0, 

; System, 

t open console keyboard on channel 2, 



; Begin the main program loop. 



LDA 0, PROMT 

.SYSTM 

,*RL 1 

JMP 3 .ER 

LDA 0, SPACP 

.SYSTM 

.RDL 2 

JMP S .ER 

LDA 2, SPACE 

LDA 1, ThORD 

SUB 1, 2, SNR 

J^P TOCLI 

.SYSTM 

,*RL 

JMP 3 .ER 

.SYSTM 

.WRL 1 

JMP 5 ,ER 

JMP LOOP 

.TXT "&<15>" 



," Point to prompt character. 

} System, 

," write prompt to channel 1 (console out). 

; Error - report via CLI. 

,* Point to beginning of line buffer, 

; System, 

; read a line from channel 2 (console keyboard). 

f Error - report via CLI, 

; Get 1st word (2 bytes) of line buffer "in AC2. 

', Put terminator *oro {I J) in AC1. 

; here 1st 2 bytes U ? (Skip if not.) 

\ Yes -- retu-r to CLI. 

,* No_-- System, 

', write line to channel 0, file W. 

? Error -- report. 

I System, 

} echo the line on console out. 

; Error_-- report, 

; New oo it ell agei n. 

J Terminator .ore, I in left byte, CR "in right. 



j Error processing rout"in. f creates file h if it doesn't exist. hhen 
I system get. here* AC8 still has * pointer, AC2 ha. error number! 



LDA I, ,ERDL 
SUB 2, 1, SZR 

JMP i ,ER 

.SYSTM 
.CRAND 
JMP 3 .ER 
JMP START 
ERDLE 



I Get cooe ERDLE (file ooes not exist). 
1 Skip next instruction if file alreaoy 
Error other than ERDLE, exit. 
System, 
create file h » 

Error, exit and report. 
New go back anc open the new file. 



exist.. 



I 
} 

i 

) ERDLE 



12. 



Figure 9- J. U *R / TE. SR Progra m wuk Errors 
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^Normal return to CLI. 



0882 WRITE 
01 

02 

03 0005l , 00fc0I7 TOCLI: .SYSTM 

dU 00052'00««00 ,rt.N 

05 00053»002000- j.mp s FR 

06 

07 * Filenames, prompt, buffer, etc, 

08 

09 0005a«000132-Nrti . + 1*2 

10 00055 , 053«00 .TXT "W" 
11 

FU00056«000000 NTTO .+1*2 
13 00057«02212a .TXT "STT0" 

1« 052060 

15 000000 

16 00062 , 000ia6"NTTl: , + 1*2 

17 00063«02212a .TXT "STTI" 

18 052111 

19 008000 
20 

21 00066'003156"PROMT: .+1*2 

22 00067«037ai5 ,TXT "?<15>" 

23 000000 

2a 

25 00071 »00016a"SFACP: SPAC£*2 
26 

27 00072*000103 SPACE: .BLK 132. /2 + 1 

28 

29 

30 ; Error return to CLI. 

31 

32 00175«006017 ERROR: .SYSTM 

33 00l76'006a00 .ERTN 
3« 00177»802000- JMP 3 ,ER 
35 

UU .END START 



J System, 

\ return to CLI. 

; Error (can't happen}. 



I Point to f i lename K» 

» 

; Point to filename STTO. 



; Point to filename STTI. 



l Point to prompt 
J ■?" anc CR U). 



! Point (aacr*2) to 1st byte in line buffer, 

; 133. bytes for read/write line buffer- 
# let the assembler compute it. 



; System, 

', return to CLI and have CLI report. 

; Error (can't happen). 



**00008 TOTAL ERRORS, 00000 PASS 1 ERRORS 



Figure 9-3. WRITE. SR Program with Errors (continued) 



The program .ENTers its starting address, START, not 
because other modules will use it, but because we want 
to identify START symbolically to the debugger. Later 
this will help us debug the program. The .ENT line is 
flagged with a GU error. 



The .ZREL pointer on line 1/6 points to error handler 
ERROR at the end of page 2. Through this pointer, al- 
location in 32K words can get to ERROR. Without the' 
pointer, ERROR would be nearly out of range of the 
JMP in line 1/20. Ail system calls except the first, 
.APPEND, make use of this .ER pointer for their error 
returns. 



The .NREL in line 8 specifies normal relocation, which 
• ;;•;•.--. '.'■■ :he ">: ..:';hj ;\ er.:m 



The Slrst group of code, in lines 1/12-1/24, opens disk 
file W for appending and opens the console output and 
input files for normal I/O (line 16 has a U error). If 
.APPEND cannot open file, it takes the error return on 
1/15; this jumps to the routine on lines 1/52-1/60. This 
routine creates file W if it doesn't exist, then jumps 
back to the beginning of the program. 

The next block of code starts with LOOP and extends 
from line 1/28 to line 1/48. This code reads a line typed 
on the console, and checks to see if the first two 
characters are & and ). It does this by loading the first 
two words (two bytes or two characters) from line 2/25 
and comparing this to a match word (1/47) set up to 
contain & ), If they match, the program returns to the 
CLI via sequence TOCLI, 2/3. If they don't match, the 
program writes the entire line to disk file W, echoes it 
on the console, and returns to LOOP. 
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On most errors, the program jumps through ZREL to 
ERROR, near the end of page 2. ERROR returns via 

.ERTX, which telis the CLI to interpret the error. 



Now for the other locations. We need a byte pointer 
and text siring for filename W, STTO. STTI, and for 
the prompt C? and ). ASCII 15). Lines 2/9 through 
2/23 contain these byte pointers and text strings. 
SPACP, line 2/25, is a byte pointer to the start of the 
line buffer, needed for read and write line calls. It is 
separate from the buffer name because we need a 
unique symbol to load the first word of the buffer. Line 
2/26 establishes the buffer itself; the read call reads 
into this and the write call writes from it. 



Finally, we .END the program and direct control back 
to START. The .END statement is flagged with two U 
errors. 



WRITE.SR with No Assembly Errors 

Having corrected the seven assembly errors with 
Superedit. reassemble the program with the command: 

|ASM/XPARU/S|, WRIT J^ L L K 

{MAC f (sttoi/l) 

From this, you get a listing and an RB file. The listing 
shows no errors. You're now readv to process WRITE 
with RLDR.Type: 

RLDR/D WRITE} 

The global /D switch loads the debugger with WRITE, 
so that you can debug it later. 

RLDR types out a listing of modules loaded with the 
program, some NMAX and ZM AX figures, but no 
errors. Now to execute WRITE, type: 



The MAC listing shows 8 errors, on lines 1/2. 1/16, 
1/59, and 2/26. The ASM listing shows fewer errors, 
but in the same locations. As with error reports from 
other utilities, you cannot deduce the precise number 
of assembly errors from the number of error codes you 
receive. Take the error codes to be general indications 
of error conditions. Here, for example, all errors were 
caused by only two error conditions. The first error 
results from our use of the symbol .START. We 
intended to use symbol START as a name for the 
beginning of the program. Deleting the period from the 
symbol should clear up several errors. 



The second error clearly relates to symbol NTTO since 
all lines which contain NTTO are flagged. The problem 
lies in line 2/ 1 2 where we forgot to insert a colon after 
NTTO. Insert a colon, creating the valid label NTTO: 
and other errors should go away. 



WRITE) 

FIL EDOES SO T EX IS T: W R ITE.SV 

R 



Curious. Not only did WRITE bomb without typing its 
prompt, but stated that it didn't exist. Actually, this is 
the way .ERTN works: it passes an error code to the 
CLI, but can't pass anything else because it has only 
AC2 to work with. The error must have been code 12 g , 
which the CLI correctly interpreted as FILE DOES NOT 
EXIST. The ": WRITE.SV" appeared because the CLI 
always tries to identify the argument that caused the 
error. Here it failed because WRITE had replaced it in 
memory. When it returned, all it knew was that a 
program named WRITE.SV had issued .ERTN with 12 
in AC2. Thus, the filename argument that the CLI 
gives after a program issues .ERTN is always the 
program name itself, and you can ignore it. 
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The CLI's explanation of the error (FILE DOES NOT 
EXIST) is accurate, though. One of WR HE'S system 
calis took the error return because it could not find a 
file. This particular call must be one of the first three 
calls because WRITE didn't type the prompt on the 
console. It couldn't have been the .APPEND call, 
because .APPEND will jump to a file-creating routine if 
its file doesn't exist. Therefore it must be one of the 
console-opening .OPEN calls. The calls themselves 
look ok, as do the byte pointers (one of whose labels 
you fixed) on lines 2/ 1 2 and 2/ 1 6. The console device 
names on lines 2/13 and 2/17 also seem ok - but no! 
Line 2/13 has the console output name as STTO. The 
correct name is STTO. This explains the error: WRITE 
tried to open file STTO, which didn't exist. 

Using Superedit, change STTO to STTO in WRITE.SR. 
Then assemble the program again as shown earlier and 
run it through RLDR again. The assembler will delete 
the old, defective RB binary file and replace it with the 
new one; RLDR will do the same with the save file.' 

Run the new WRITE.SV again: 

WRITE) 
STTI 

At least it didn't bomb. "STTI" may not be the correct 
prompt, but it's an improvement over "FILE DOES 
NOT EXIST". Type ) 

) 



To check the disk file, you'll need to get back to the 
CLI. Try the terminating sequence (&)): 

&} 

R 



The terminator works and you're back to the CLI. Now 
what about the disk file, W? 

TYPE W) 
SOMETHING 
SOMETHING ELSE 

R 



The disk file mechanism seems fine, too. Aside from 
the initial prompt problem, WRITE seems to be in 
pretty good shape. Check by running it again: 

WRITE) 
STTI ) 



SIGH) 

SIGH 
? 



Clearly the problem isn't going to go away. Stop 
WRITE and check file W from the CLI: 



The question mark is the right prompt. Type something: 

SOMETHING) 

SOMETHING 
? 

WRITE repeated the line on the console - so far so 
good -- but we don't know whether it wrote to the disk 
file yet. The prompt problem seems to have fixed itself. 

SOMETHING ELSE) 
SOMETHING ELSE 



&) 

R 

TYPEW) 

SOMETHING 

SOMETHING ELSE 

SIGH 
R 



Everything works except the inital prompt, which is 
STTI when it should be ?. The next step is a very 
common one in assembly language programming: 
debugging. 
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Introducing the Debugger 

This section gives a debugger overview. Read it before 
you proceed to operate the debugger, as described in 
the next main section, Debugging Write. 

The debugger is a system utility that lets you examine 
and make minor modifications to examine your 
program as you run sections of it. There are two 
debuggers, IDEB, which allows you to disable device 
interrupts, and DEB, which does not. This section deals 
with DEB. You'll need IDEB only 10 debug routines 
that handle nonstandard device interrupts. For more 
on either debugger, consult the Symbolic Debugger 
manual. 

Remember that we loaded DEB with WRITE, 

assuming that we might need it later. When we've 
found the bug and corrected it, we can reload WRITE 
without DEB. 

Most debug commands employ the ESC kev, which, as 
in SUPEREDIT, echoes as "S". Here the DEB 
commands you'll be using: 



Debugger Breakpoints 

A breakpoint is a location where you want the debugger 
to stop your program during execution. This gives you 
a chance to examine the contents of the accumulators 
and to look at whatever else you want in your program. 
You may setup to eight breakpoints in a program. Each 
breakpoint address you specify can be either an 
absolute number or a symbolic expression. Symbolic 
expressions are easier. You can use each location you 
.ENTered in a program to specify a breakpoint address; 
e.g., LOOP + 3 or ER + 1, if you had .ENTered LOOP 
and ER. By entering START in WRITE, named a 
symbolic location that you can use in debugger address 
expressions. 



Changing Display Format 

Initially, the debugger displays the contents of locations 
in octal; this is the default mode. You can change it 
within a command line by typing one of the following 
local commands (we don't show them all here): 



Command Meaning 

ladrj'i Display contents of adr. 

facJSA Display contents of one or all 

accumulators. 

[debug-adr] SB Insert a breakpoint at debug-adr, or 
display all breakpoints. 

in] SD Delete one or all breakpoints. 

SP Proceed to execute the program 

from the current breakpoint. 

fadrjSR Run the program from the 

beginning, or from adr. You must 
issue SR initially; then you can use 
SP, oradrSR. 

SV or CTRL-A Leave the debueeer and return to 

theCLI. 



Command Meaning 

= display last item in octal. 

display last item in ASCII. 
; display last item in instruction format (e.a., 

LDAO, OUTPUT) 
? displav last item in .SYSTM call format (c.c. 

.WRLO) 
&. display last item in byte pointer format (e.c, 

000522 0) 



You can change the entire output mode of the 
debugger by typing ESC, then one of these commands; 
the new mode will remain until you change it. For 
example. S' tells the debuceer to display evervthine in 
ASCII. 



NEW LINE/ 
LINE FEED 
UPARROW If) 



These commands control the 
format of debugger display; we 
describe ihem below. 

These tell the debugger to proceed 
or back up one location. 



The debugger doesn't understand DEL or RUBOUT, 
nor does it accept ESCape commands in the middle of a 
line. If you type something it doesn't like, it will display 
a "U" or question mark (?). then output a return and 
wait for another command. 
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Examining and Changing Memory Locations 

You can display the contents of any location by typing 
the symbolic or numberse address of the location 
followed by a stash. For example, 

START/ 020454 

displays the contents of START. START is a debug 
address. (Remember that we show user input in 
boldface type and system output in /w//ciype.) To 
display successively higher locations, press the NEW 
LINE key, or if your terminal doesn't have a NEW 
LINE key, the LINE FEED key. We show this key as 
downarrow (f ) although the debugger doesn't echo it at 
all on the terminal. To display successively lower 
locations, type uparrows via the SHIFT-6 or SHIFT-N 
key. We show uparrows as (f ) , as does the debugger. 
For example: 



START+I 
START +2 
START+I 



006017, 
012400 ■ 
00601 7 



Octal numbers by themselves don't mean very much. 
You can tell the debugger to interpret them by typing 
one or more local display commands. 

For example, address START contains an octal 
number: 

START/ 020454 

Semicolon (;) displays this number in instruction 
format: 

;LDASTART + 54 

Question mark (?) displays it in .SYSTM call format: 
7.CCON54 
Apostrophe {') displays it in ASCII format: 



and finally, ampersand {&) displays it in byte-pointer 
format: 

& 010226 

For any location, only one local display command gives 
a useful picture of the contents. If a locations holds an 
instruction, like JMP LDA, the appropriate command 

is ";", which displays in instruction format. The 
assembler listing can help in this process; for example, 

the listing in Figure 9-3 tells you that START contains 
an instruction, thus the semicolon is the appropriate 
display command. 



If a location holds a system call, like .OPEN 1 or .RDL 
2, the appropriate command is ""?", which displays in 
.SYSTM call format. If a location holds ASCII 
characters, like ST or W, the appropriate command is 
"'", which gives ASCII format. For a byte pointer, like 
ST, the command is &, followed by a slash, which 
displays the contents of the location pointed to. 
Usually, you can tell which kind of display command is 
correct because other commands will give absurd 
results, like. CCON 54 and !, and 010226 above. 

To change the contents of memory location, display the 
location with a / or | or | command, then type in the 
contents you want and press ). The new contents can be 
an octal number or it can be an instruction like LDA 0. 
START 4-55. A word of caution about changing 
locations: the computer will execute the new contents 
without asking questions, so problems could occur if 
you make a mistake. Also, be wary of changing a 
location's contents accidentally. If, when a location is 
open, after /or J, or f, you inadvertently type 
something and press ), the character(s) you typed may- 
replace the old contents of the location. These new- 
contents may cause problems when you run the 
program. If you suspect that you have accidentally 
modified a location, and haven't yet pressed ), press 
the DEL or RUBOUT key. The debugger will reject the 
entire line and then will type ? or U; you can then 
proceed. If you /w re pressed } after accidentally- 
changing something, type CTRL-A to get back to the 
CLI and type the debug command again; this will bring 
the original program (which remains unchanged on 
disk) back into memory. 

Starting or Continuing to Run Your Program 

To run your program for the First time, type SR; 
thereafter you can proceed with program execution by 
typing P or addrSR. For P, the debugger will proceed at 
the address contained in P, the program counter. 
Initially, P contains the value specified by the .END 
pseudo-op in the assembly language source program. If 
you are waiting at a breakpoint, P contains the address 
at which execution stopped, so all you have to do is type 
SP to continue where you left off. 

Ending a Debugging Session 

When you are done debugging and want to return to 
the CLI, simply type 

SV (or CTRL-A) 

The changes you have made to your program during 
the debugging session do not become part of the disk 
file when you leave the debugger. To make permanent 
changes to your program you must go through the cycle 
of editing your source program, assembling it, and 
processing it with RLDR. 
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Debugging WRITE 



You've discovered and eliminated the assembly and 
filename errors from WRITE. It now runs properly, 
except for its first pass, when it displays STTI instead of 
? for a prompt. 

Now, having reviewed debugger fundamentals, you 
can use the debugger to find out why WRITE gives the 
erroneous prompt. 

Type 

DEB WRITE) 

to activate the debugger, which responds with a 
carriage return. The carriage return is its prompt, like 
Superedit's !. 

You're ready to start debugging. The critical lines in the 
program assembler listing haven't changed, so you can 
use this as a guide. First, let's think about the problem. 
AH system calls and logic in the program work, but the 
.WRL in line 1/30 (Figure 9-3} gives STTI as an initial 
prompt, instead of the ? that line 1/28 specifies. After 
the program runs through the loop once, it gives the 
correct prompt. The problem must be somewhere 
around 1/28, because the LDA isn't working on the 
first pass. 

For practice, take a look at the locations around 
START. Start with START: 

START/ 020454 ; LDA OSTAR T+54 

Press I to open and display the next location: 

i 
START+J 006071 ;JSR @ + 17 

This is what the .SYSTM mnemonic before each 
system call looks like in memory. It is a JSR to location 
17 R , from which location the system processes the 
svstem call. 

i 
START+2 012400 ; 1SZ START +2 ? .APPE 

There's the .APPEND system call word. The debugger 

displays only five characters. Without the preceeding 
.SYSTM word, the computer would have executed the 
012400 as the ISZ instruction - which is not what you 
want. 

i 
START +3 000436 ; J MP START + 41 



This is the error return from .APPEND, which goes to 
NOFIL on line 1 /53. Try backing up a location: 



START +2 012400 

Jump around a bit: 

) 

START + 100/ 000000 ;JMP0 } 

This is an empty word in the line buffer, not a JMP 
instruction. 

START + 37/ 023015; LDA +I52'& <15 > ) 
This is the matching TWORD at line 1/47. 



Having looked around, trv setting a breakpoint at 

START. 

Type: 

STARTSB 

This sets a breakpoint at the location immediately 
preceding ST ART. Display the breakpoints: 

SB 

7 B START 



The debugger names the first breakpoint 7B, the 
second 6B, and so on, to the eighth breakpoint, 0B. 

Run the program: 

SR 

7 B START 

000000 1 000000 2 000000 3 000000 



When control reached the breakpoint, it went to the 
debugger, which displayed the breakpoint name, 7B, 
location, START, and the contents of the 
accumulators. AC0, ACi, AC2, and AC3 and each 
contain since the program hasn't loaded anything into 
them yet. 

Set another breakpoint at the next location, START+ 1: 
START + 1 SB 
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After you have type SR once, you use SP to proceed 
with the program. You can use SR again onlv ifvou 
precede it with an address, like START. Type: * 

SP 

6B START +1 

001244 1 000000 2 000000 3 000000 

Something got into ACO -- looks like a byte pointer. 
You can check by displaying ACO's contents in 
byte-pointer format, then displaying the byte pointer 
location's contents in ACSII: 

OSA 001244 & 000522 ) 

ACO contains 1244, which, in byte-pointer format, is 
522. Now what does 522 contain in ASCII? 

552/ 053400 ' W <0> 

It contains W for the disk filename -- as it should. 

Return to START + 2 and move forward to the next 
LDA instruction: 

START + 2/ 012400 l.APPEOl 
START +3 000436-JMPSTART+41 I 
START+4 020452 ; LDAOSTART+56 1 
START+5 126400 ; SUB 1 1 

This looks like a good place - after the LDA instruction 
in START + 4. Set another breakpoint and proceed: 

) 

START + 5SB 

SP 

5B START+5 

001250 1 00000 2 000000 3 000000 

Another byte pointer in ACO; check it out: 

OSA 001250 & 000524 524/ 022124 ' ST 

ACO contains a pointer to a text string beginning with 
ST. The LDA in START + 4 worked and everything is 
ok thus far. 

Now, get to LOOP and see if the byte pointer to the -> 
prompt gets loaded: 

) 

START + 13/ 014002 ;DSZ +2 ? OPEN ? I 

START+14 020452 ; ID A ST ART +66 

Set another breakpoint after the LDA in START+ 14: 

) 

START +15SB 

SP 

4 B START +15 

001260 1 000000 2 000000 3 000000 



ACO contains 1260, which should be a bvtepointer to 
the prompt (? < 15 > ). Check it out: 

OSA 001260 & 000530 530/ 022 1 24 'ST 

The "ST" doesn't look much like the prompt, but try 
the next location: 

START+64052111 ' Tl 



ACO still has the byte pointer to STTI, not to ? < 1 5 > 
as it should. This explains why WRITE says STTI 
instead of ?. It means that the LDA in location LOOP 

isn't happening. Why not? Continue the program: 

) 

SP STTI 



This is WRITE's .WRL at line 1/30. Tvpe some text 
next to the STTI prompt: 

FOO) 
TOO 
4BSTART+15 

001270 1 000004 2 027070 3 000000 

WRITE has jumped back to LOOP and is executing the 
LOOP breakpoint again. AC1 shows the bvte count 
including the CR (carriage return), from the .WRL on 
1/44; the byte counts from .RDLs don't include CRs 
AC2 shows the results of the SUB on line 1/38. 



But ACO differs from the first time you saw this 
breakpoint. It probably has the right bvte pointer now 
Check it: 

OSA 001270 & 000534 534/ 037415' ? < 15 > } 

Yes. This is the right prompt. WRITE will display it 
when you proceed: 

SP ? 



? is the correct prompt. Try typing something else: 

ZUTALORS) 
ZUTALORS 

4B START +15 

001270 1 000012 2 032110 3 000000 

The byte pointer in ACO remains the same, which is 
consistent with your earlier experience: WRITE gave 
the correct prompt every time after the first pass. 
Clearly the loop is ok now. 
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The debug session has shown that WRITE skips the 
LDA m line LOOP for its first pass, but executes this 
LDA correctly thereafter. Now why does it do that? 

Because we forgot the error return from the .SYSTM 
call that opens the console input file, line 1/25. 

The error return and the .SYSTM word are essential 
parts of each system call, but people too often forget 
them. In this case, the system opens file STTI 
normally, but assumes that the LDA in line LOOP is 
the error return, thus the system skips it. When 
WRITE gets to the .WRL for the prompt, ACO still 
contains a byte pointer to STTI, which is why you get 
STTI for the first prompt. 

At the end of the loop, WRITE jumps back directly to 
LOOP, so the LDA executes properlv after the first 
pass. 

The solution is easy once you know the problem For 
verification, use the debugger. First, get out of the 
debugger and restart it: 



CTRL-A 

1ST 

R 

DEB WRITE) 



Set the critical breakpoint and run the program: 

START+15SB 

7 BSTART+!5 

001260 1 000000 2 00000 3 000000 

Correct the byte pointer in ACO: 
OSA 001260 1270) 
Verify the change: 

OSA 001270 & 000534 534/ 037415 ' > ' < 15 > ) 



Looks good. Now when you proceed, WRITE should 
say? ), not STTI: noulfl 



SP? 



Solid. The right prompt on the first pass. The problem 
is definitely the missing error return, which you must 
insert with Superedit. Get back to the CLI: 

&) 
R 

If you check file W (TYPE W)),youlI find that the test 
lines typed during the debugging process were 
appended to it. 

Final Version of WRfTE 

Get into WRITE.SR with Superedit, and insert a JMP 

@ .ER instruction after the .OPEN 2 call in line 1/24 
Don t msert ) (CR) if you want the assembler listing 
line numbers to remain the same. Simplv tvn- 
something like: 

!JSSNTTiSS@STSS 

. OPEN 2(\); open console keyboard 
!S) 
STSS 

HtabJMP ©.ERS-2LS4TSS 

•SYSTEM ; System 

• OPEN 2 ; open file W 

JMP @ .ER 
: Begin the main program loop. 

WD, n 4° S D e th£ me (UESHSS) - ^d reassemble - 

oi k T^n " ,l J hrou S h RLD * again, wnhomihe 
global /D switch: 



RLDR WRITE 



SLPT/L ) 
STTO/L > ) 

sttoi/lI 



Figure 9-4 shows the final version of WRITE, including 

the cross reference. Shaded areas indicate chances 
from the initial version. 
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€001 WRITE 



02 
03 
8a 
05 
456 
87 
08 
89 
10 
1 i 
12 
13 
la 

15 
16 
17 
18 
19 
20 
21 
22 
23 
2a 
25 
26 
27 
28 
29 
30 
31 
32 
33 
3a 
35 
36 
37 
38 
39 
a0 
ai 
12 
a3 
aa 
a5 
a6 
a7 
as 

49 
50 
51 
52 
53 
5a 
55 
56 
57 
58 
59 
60- 



000001 



MACRO REV 06.30 

.TITL WRITE 
.ENT START 
.TXTM 1 



00000-000176' »ERS 



,ZREL 
ERROR 



17:58:t3_ 04/02/79 

I Title {• optional but sometimes useful. 

; Global entry for debugging 

I Pack text bytei left to right. 

t Pointer in page zero avolct assembler A error, 
; ,ER containa "ERROR" acoreaa in NREL apace. 



00000 
00001 
00002 
00003 
0000a 
00005 
00006 
00007 
80010 
00011 

00812 
00013 
000ia 



820a55 

006817 

012«08 

008a37 

020453 

126480 

806817 

014001 

002000. 

020^52 

886817 
0U002 
802000- 




J Begin the main program loop. 



00015 
00016 
00017 
00020 
00021 
00022 
00023 

0082a 

00025 
00026 
00027 
08030 
00031 
00032 
00033 
0003a 
00035 
00036 
00837 

00040 



•028452 

'006017 

•017001 

•002000' 

•020a5l 

•006817 

'815a82 

•002088" 

•030446 

•02aai2 
»132a05 
•888422 
•006017 
•017000 
•002000' 
•006017 
•017001 
•002000. 
•000756 
•023015 
000000 



LOOPS LDA 0, PROMT 
.SYSTM 
.WRL 1 
JMP 3 ,ER 
LDA 0, SPACP 
.SYSTM 
,RDL 2 

jmp a ,er 

LDA 2, SPACE 
LDA 1, T'rtGRD 
SUB 1, 2, SNR 

JMP TOCLI 
.SYSTM 
,WRL 
JMP 3 ,ER 
.SYSTM 
.WRL 1 
JMP 3 ,ER 
JMP LOOP 

tworoi ,txt "&<i5>" 



buf f er , 

(conaole keyboard) 



Point to prompt character. 

System, 

write prompt to channel 1 Cconaole out). 

Error - report viaCLI, 
Point to beginning of line 
System, 
read a line from channel 2 

Error - report via CLI. 
Get .lit word 12 bytea) of line buffer in AC2. 
Put terminator word ( & ^ ) in AC1. 
here 1st 2 bytes &J ? (Skip "if not.) 

Yea -• return to CLI. 
Nc_ •• System, 
write line to channel 0, 

Error •• report. 
System, 
echo the "line on console out. 

E r r o r _ • - report. 
Now do "it all agai n. 
Terminator word, & in left byte, CR "in right. 



file h. 



I Error processing routine, creates file W "if it doesn't exist. When 
I syatem gets here, AC8 still has W pointer, AC2 has error number. 



00042» 
080a3» 
80044' 
00845 1 
80046» 
080«7» 
00858 , 
80051 • 



02a407 

146«04 

002800. 

08601? 

007000 

002000. 

800730 

808812 



NOFILI LDA I, .ERDL 
SUB 2, 1, SZR 
*JMP 3 .ER 
.SYSTM 
.GRAND 
JMP 3 »ER 
JMP START 

.ERDLt ERDLE 



I Get code ERDLE (file does^not exist). 

\ Skip next instruction if fU« already exists, 

} Error other than ERDLE, exit, 

; System, 

\ create f i le_ W* 

f Error, exit and report. 

} Now go back and open the new file, 

; ERDLE as 12. 



Figure 9-4. WRITE. SR Program without Errors 
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0002 WRITE 
01 fNormel rtturn to CLI, 

02 

01 00052'006017 TDCLIS .SYSTM ,* System, 

04 00053*004400 ,RTN I return to CLI. 

05 00054»002000- JMP a ,ER ? Error Ccan*t happen), 
06 

07 i Filename** promptf buffer* etc, 

08 

09 00055»008l3a"NWI ,+1*2 I Point to filename ft, 

10 00056*053400 .TXT "W ; 
11 

12 00057*000140"NTTOS . + 1*2 - . ; Point to filename STTO. 

13 00060*022124 *— — « " ,JXT "STTO" } 

14 052 117 

15 000000 

16 00063'000150 M NTTIS .+1*2 ; Point to filename $TTI. 

17 00064*022124 .TXT "STTI" I 

18 052111 

19 000000 
20 

21 00067'000160"PROMT{ ,+1*2 ; Point to prompt 

21 00070«037415 .TXT "?<15>" ; "?" and CR C>). 

23 000000 
24 

25 00072»000166"SPACPS SPACE*2 ; Point (ader*2) to 1st byte in line buffer, 
26 

27 00073*000103 SPACES ,BLK 132, /2+1 ! 133. bytes for read/write line buffer- 

28 J let the assembler compute it, 
29 

30 ?Error return to CLI. 

31 

32 00176'006017 ERRORS .SYSTM ; System, 

33 00177'006400 ,ERTN ; return to CLI and have CLI report, 

34 00200*002000- JMP 3 ,ER ; Error (can't happen), 
35 

36 .END START 

**00000 TOTAL ERRORS, 00000 PASS 1 ERRORS 

00e3 fcRITE 

ERROR 000176* 

LOOP 000015' 

NOFIL 000042' 

NTTI 000063' 

NTTO 000057' 

NK 000055* 

PROMT 000067' 

SPACE 000073' 

s f a : » e e e ? 7 2 • 

START 000000* EN 

TOCLI 008052' 

TfcDRD 000040* 

,ER 000000- 1/06 1/20 1/25 1/31 1/35 i/«2 l/«S 



1/06 


2/32 






1/28 


1/46 






1/15 


1/53 






1/21 


2/16 






1/16 


2/12 






1/12 


2/09 






1/28 


2/21 






1/36 


2/25 


2/27 




1/32 


2/25 






1/02 


1/12 


1/59 


2/36 


1/39 


2/03 






1/37 


1/47 






1/06 


1/20 


1/25 


1/31 


1/55 


1/58 


2/05 


2/34 


1/53 


1/60 







Figure 9-4. li 'RJTE.SR Program without Errors (continued) 
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Figure 9-5 shows RLDR information (called a load 
map) from WRITE. 

The RLDR load map, shown for WRITE in Figure 9-5, 
shows the module names and program size 
information. It also gives some module starting 
addresses, which makes a useful debugging tool. 
although you didn't use it during this debugging 
session. In Figure 9-5, WRITE is the TITLof the 
module. TMIN is the single-task scheduler. If WRITE 
were a multitask program, you'd have specified the 
number of tasks with the local /K switch in the RLDR 
line, and the RLDR would have loaded the multitask 
scheduler, TCBMON. 



NSAC3 tells the system to copy the contents of location 
16 gf the USP or User Stack Pointer, into AC3 after 
each system or task call. Thus you can use USP, a 
handy ZREL location, to store the return address from 
a subroutine. No matter how the subroutine uses AC3, 
a system or task call will restore it to the value it had on 
entry. The program can then JMP 0,3 to return from 
the subroutine. The .ENT pseudo-op in Chapter 8 
shows an example of USP usage. 



fcRITE.SV LOADED BY 
RLDR REV 07.10 AT 17:59;02 04/02/79 



WRITE 




TMIN 




NSAC3 




NMAX 


000742 


ZMAX 


000051 


CS2E 


000000 


EST 


000000 


SST 


000000 


USTAD 


000400 


START 


000445 


TMIN 


000647 


.SAC0 


020016 


.SAC1 


024016 


.SAC2 


030016 


.SAC3 


034016 



Figure 9-5. RLDR Load Map from WRITE 



NMAX, the first unused word of NREL memory 
above WRITE code, is 742 g . ZMAX, the first free word 
of ZREL memory, is 5l„ because the program uses 
location 50 8 for the ERROR pointer. CSZE is the 
FORTRAN COMMON area size; here there is no 
COMMON. EST is the (bottom) of the symbol table. 
SST is the start of this table. The symbol table helped 
you debug WRITE, but you didn't tell RLDR to load it 
(global /D) with this version of WRITE, hence, figures 
for it are zero. 

USTAD is the starting address of WRITE's User Status 
Table. RLDR builds this table into each program and 
the system uses it to store runtime information on the 
program. START is WRITE's START address. TMIN, 
the task scheduler, starts at 647 g . The .SAC entries are 
LDA instructions, not locations. RLDR takes them 
from the module NSAC3, described above. 



Running WRITE 

WRITE should run properly now; you've spend 
enough time on it. Try it out: 

WRITE} 

You've fixed it; the intial prompt is correct. 

WRITE RUNS RIGHT, Q.E.D.) 
WR I TE R UNS R IGH T, Q, E. D. 



&} 
R 



TYPE WJ.and find that it contains all messages. 
WRITE is right, and all ventures into Superedit, the 
assembler, RLDR and the debugger have paid off. 
WRITE is a neat little program, and you can use it, or 
parts of it, to produce impromtu logfiles and do other 
things. 

In the future, if you plan to do a lot of assembly 
language programming, you might want to create a 
directory (e.g., ASM.DR) for your assembly language 
programs, and link to the needed utilities from it. 
You'll need links to the following files* 
(N)SPEED.SWSPEED.ER, ASM.SV/XREF SV or 
MAC.SV/MACXR.SV/MAC.PS 
RLDR.SV/RLDR.OL, and SYS.LB 



End of Chapter 
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Index 



Within ihis index, the letter "f" means "and the 
following page"; "IT" means "and the following 
pages". For each topic, primary page references are 
listed first. All letters are lowercase, except CL1 
commands (e.g., BUILD), Superedit commands (e.g., 
C). FORTRAN, BASIC or assembly lanauase svmbols 
(e.g., FORMAT, LIST, JSR), pseudo-ops (e.g., '.BLK), 
and system calls (e.g., .GRAND). 



) (RETURN) iv 

! (exclamation point) prompt 5-lf 

* (don't load accumulator) assembly language 8-7 
S (ESC) Superedit command 5-1 

S (ESC) debugger command 9-12 

5 (dollar sign) BASIC strings 7-3 

6 debugger command 9-12 

' (apostrophe) debugger command 9-12 

* (asterisk) CLI template 2-6, 3-6f 
-f (plus) addition 

assembly language 8-5 
BASIC 7-2 

- (dash) subtraction 

assembly language 8-5 
BASIC 7-2 

* multiplication in FORTRAN, BASIC, 
assembler 6-3, 7-2, 8-5, 9-1 

* (BASIC prompt) 7-2 

- (dash) CLI template 2-6, 3-6f 
. (period) current location 8-4 

. (period) indicates decimal to assembler 9-4 
/ (slash) CLI switch indicator 2-3, 3-3 
/debugger command 9-12 
/ division in FORTRAN, BASIC, assembly 
language 6-3, 7-2, 8-5,9-1 
: (colon) directory specifier 2-7, 3-7 
: (colon) in label 8-2 
; (semicolon) in CLI 4-1 

; (semicolon) indicates comment to assembler 8-2 

; (semicolon) debugger command 9-12 

? debugger command 9-12 

@ (indirect addressing) assembly language 8-7f 

| (uparrow) in CLI 4-1 

f (uparrow) debugger command 9-12 
f exponentiation in BASIC 7-2 
1 (NEW LINE/LINE FEED) debugger 
command 9-12 ** exponentiation in FORTRAN 6-3 



A debugger command 9-12 

ADD instruction 8-6 

AND instruction 8-6 

AND (logical) 8-5f 

.APPEND svstem call 9-3, 9-5ff 

arrays (BASIC) 7-2f 

arithmetic-logical instructions see instructions 

ASM 8-1, 9-7, also see assemblers 

assemblers 8- Iff 

command lines 9-7 

instruction set 8-5ff 

operators 8-6 

program listings 8-2f, 9- 1 7f 

pseudo-ops 8-7ff 

relocatable binary file 8-lf 
asterisk see * 



B 



B (debugger command) 9-12 
backing up vour files 

DOS 3-9f, 4-6f 

RDOS 2-1 Off, 4-6ff 
backup file 4-13.5-3,5-6 
BASIC programming 

MORTGAGE program 
analysis 7-6 
flow chart 7-4 
listing 7-5 

overview 7- If 

sample session 7- Iff 

strings and arrays 7-2f 

writing programs 7-1 
.BLK pseudo-op 8-9, 9-9f 
bootstrapping 

DOS 3- If 

RDOS 2- If 
BREAK key 2-2,3-2 
breakpoints (debugger) 9-12 
buffer 

location in memory 9-8ff 

superedit edit 5-2 
BUILD command 4-2 
byte 

definition 9-1 

pointer 9-1 
fixing 9-15 
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C command (Superedit) 5-4 

case (of characters) 5-1, 2- If, 3-lf 

carry bit 8-6 

CDIR command 4-3, 2-4f, 3-5f 

changing text 5-4 

character pointer 5- Iff 

CLG command 6-6 

colon see : 

command line interpreter see CLI 

comments in programs 

assembly language (;) 8-2f 

BASIC (REM) 7-2f 

FORTRAN (C) 6-3 
common CLI commands Chapter 4 
communication between modules see .ENT, .EXTD, 
EXTN 

compiler (FORTRAN) 6-1,6-2,6-4 
console 

filenames 9-5 

using 2- If, 3-lf 
control characters 

Superedit 5-2 

universal 2-2, 3-2 
CP 5- Iff 

CPART command 4-3,2-6 
CRAND command 4-4, 2-2f, 3-3 
.CRAND system call 9-2,9-8 
cross-reference listing 8-4 
CTRL 

Superedit 5-2 

universal 2-2, 3-2 

D 

dash see - 

DEB command 9-14 
debugger 9- 1 2ff 
commands 9-12 
breakpoints 9-12 
changing display 9-12 
changing locations 9-13 
loading 9-10, 9-16 
r;.:m:ng ;-' gr.mi '--'.3 
definitions 

assembly language 

byte pointer 9-1 

instruction set 8-5f 

module 8-1 

operators 8-5 

pseudo-op 8-8 

symbol 8-4f 
map 1-2 
multitasking 1-1 
operating systems 1-1 
system call 9- Iff 
task call 9-2 
DEL key 2-2.3-2.5-2 
DELETE command 4-4f, 2-3, 3-3 



deleting 

files see DELETE 
text (K command) 5-6 
device 

codes 2-1, 3-1 
console filenames 9-5 
disk names 2-2, 3-3 
DIM statement (BASIC) 7-2ff 
D1R command 4-5,2-5,3-5 
directory 

definition of 1-2 
file 2-4f, 3-4f 

for assemblers 9-7 
for FORTRAN 6- If 
for BASIC 7-1,7-8 
for Superedit 5-2 

initializing 2-4ff, 3-5ff, also see INIT 
master 2-2, 3-3 

releasing 2-1 Of, 3-8, see also RELEASE 
specifier (:) 2-7, 3-7 
DISK command 4-6, 2-3,3-4 
Disk Operating System see DOS 
disk (ette) 

device codes 2-1, 3-1 
names 2-2, 3-3 
DOS 

bootstrapping 3-1 
CLI Session Chapter 3 
definition of 1-1 
dollar sign see S 
DSZ instruction 8-6 
DUMP command 4-6f, 2-1 Off, 3-9f 

E 

edit buffer 5-2 

editing text see Superedit 

ENDLOG command 4-7.2-11,3-11 

.END pseudo-op 8-9 

.ENT pseudo-op 8-10 

ENTER command (BASIC) 7-2ff 

entry for module see .ENT 

errors 

in assembly language program 9-8 to 9-16 

in BASIC program 7-5ff 

in FORTRAN program 6-3ff 

return from system call 9-2, 9-5 

system call 9-5, 9-10 

tvping 

in CLI 2-2,3-2 
in Superedit 5-2f 
.ERTN Svstcm Call 9-5, 9-10 
ESC 

debugger command 9-12 

Superedit command 5-lf 
example programs see programs 
.EXTD pseudo-op 8-11 
.EXTN pseudo-op 8-12 
extension to filename 1-2 
external module see .EXTN, .EXTD 
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file 

attributes 4-1 Of 

backup 2-1 Off (RDOS), 3-9f (DOS), 4-6 

BASIC files 7-2ff 

definition of 1-2 

directory see directory, file 

extension 1-2 

required for 
assemblers 9-7 
BASIC 7-1 
FORTRAN 6-1 

source 8-1 

transfer see XFER, DUMP, LOAD, MOVE, COPY 
filename extensions 1-2,8-1 
FORT command 6-2,6-4 
FORTRAN programming Chapter 6 

compiling program 6-2, 6-4 

executing program 6-5f 

loading program 6-5 

required files 6-1 

writing program 6- If 



GDIR command 4-8 



H command (Superedit) 5-5 



I command (Superedit) 5-3 
INIT command 4-9, 4-8 
initializing 

directories 4-8, 2-5, 2-8, 3-5 3-8 

tapes 4-8,2-10f 
inserting text 5-3 
instructions (assembly language) 8-5f 



I 

J command (Superedit) 5-6 
JMP instruction 8-5 
JSR instruction 8-5 



L 

L command (Superedit) 5-5 

labels (assembly language) 8-2f 

LDA instruction 8-5,9-8,9-15 

LINK command 4-9, 2-8f, 3-8f 

LIST command 4-10f. 2-3f, 3-3f 

LIST command (BASIC) 7-2ff 

listing assembly-language programs 8-2f 

listing file switches 9-7 

LOAD command 4-1 If, 2-1 1 

loader see RLDR 

LOG command 4-12,2-2,3-3 

log file (LOG.CM) 2-2,3-3 

lowercase see case 

M 

M command (Superedit) 5-5 
MAC 8-1, 9-7, also see assemblers 
MAC.PSfiie 9-7 
macro 

assembler 8-1 f 

file CMC) in CLI 2-3,3-2 
manuals, related iv 
master directory 

DOS 3-3 

RDOS 2-2 
MDIR command 2-2,3-3 
memory 

managing 1-2 

reference instructions see instructions 
MESSAGE command 2-3,3-4 
mistakes, typing 2-2, 3-2 

in CLI 2-2,3-2 

in Superedit 5-2f 
module (definition of) 8-1 
MOV instruction 8-6 
MOVE command 4-13, 2-4f, 3-5 



N 



names 

console 9-5 

disk 2-2,3-3 
NMAX 6-5,9-19 
NREL 9-19 

.NREL pseudo-op 8-12, 9-8f 
numbers (assembly language) 8-5 
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.OPEN system call 9-3, 9-8 
operators (assembly language) 8-5f 
OR (logical) 8-6 



P debugger command 9-12f, 9-15 
partition, secondary 4-3, 2-6 
period see . 

pointer, characters 5- Iff 
PRINT command 4-14 
PRINT command (BASIC) 7-2ff 
program development overview 1-1 
program load steps 
DOS 3-1 
RDOS 2-1 
programs 

assembly language (WRITE) 
flowchart 9-6 
listing (errors) 9-8f 
listing (fixed) 9-1 7f 
BASIC (MORTGAGE. BA) 
flowchart 7-4 
listing 7-5 
FORTRAN (MORTGAGE.ER) 
flowchart 6-2 
listing 6-3 
pseudo-ops 8-8ff 



R debugger command 9- 1 2f, 9-15 
-RDL Svstem Call 9-4,9-8 
RDOS 

bootstrapping 2-1 

CLI session Chapter 2 

definition of 1-1 
Real-Time Disk Operating Svstem see RDOS 
RELEASE command 4-14,2-8,3-7 
relocatable loader see RLDR 
RENAME command 4-15.2-4.3-5 
related manuals iv 
RLDR utility 

assembly-language program 9-10, 9-16. 9-19 
memorv map 9-19 

FORTRAN program 6-5 
load information 6-5 
-RTN System Call 9-5. 9-8 
rubout 

CLI 2-2,3-2 

Superedit 5-2 
RUN command (BASIC) 7-2ff 



S command (Superedit) 5-4 
searching for text strings 5-4 
secondary partition 4-3, 2-6 
shift accumulator 8-6 
shutting down 

any user program type CTRL- A 

BASIC system 7-2,7-8 

debugger 9-13 

DOS system 3-11 

RDOS system 2-12 

Superedit 5-6 
soft console 2- If, 3-lf 
Strings (BASIC) 7-2f 
ST A instruction 8-5 
starting up 

assembly-languaee program 9-10 

BASIC system 7-2 

debugger 9-13 

DOS system 2- If 

FORTRAN procram 6-5f 

RDOS system 3-lf 

Superedit 5-2 
SUB instruction 8-6, 9-8 
subdirectory 2-4 
summaries 

debugger commands 9-13 

instruction set 8-5f 

program development 1-1 

pseudo-ops 8-7 

Superedit commands 5-2,5-7 

system calls 9-2 
Superedit 

commands 5-2ff 

features 5-1 

in BASIC 7-3 

mistakes ih 5-2f 
switches 

CLI 4-1,2-3,3-3 

listing file 9-7 
symbol file (macroassembler) 9-7 
symbols 

assembly lancuace 8-4f 

CLI 4-1 

documentation iii 
system 

call 9- Iff 

DOS see DOS 

RDOS see RDOS 

type of 9-7 
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T command (SuperediU 5-3 

tab (CTRL-I) 5-3 

tape 

backup 2-1 Off 

device names 2-10 

flies on 2- 1 Of 

usage 2- 1 Of 
templates ('and -) 2-6, 3-6f 
terminal, using 2- If. 3-lf 
terms and concepts 1-1 f 
text 

changing 5-4 

deleting (K command) 5-6 

inserting 5-3 

strings, search for 5-4 

typing lines 5-3 
text editor seeSuperedit 
.T1TL pseudo-op 8-13, 9-6, 9-16, 8-13, 9- 
TXT pseudo-op 8-13, 9-8f 
TXTM pseudo-op 8-13,9-8 
TYPE command 4-15 
typing lines of text 5-3 
typing mistakes see mistakes 



UE command (Superedit) 5-6 

UNLINK command 4-16,2-9,3-8 

uppercase see case 

US command (Superedit) 5-6 

user parameter file (PARU.SR) 9-1, 9-" 



virtual console 2- If, 3-lf 



.WRL System Call 9-4,9-8 



XFER command 4-16, 2-3, 3-3 



ZMAX 6-5,9-19 

ZREL pointer 9-19 

.ZREL pseudo-op 8-14, 9-8f 
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